TypeScript Reference ยท tsconfig: Language, Modules and Emit Options
TypeScript baseUrl option
Reference for the baseUrl compiler option: how non-relative imports resolve against a folder, how it combines with paths, and why it is now considered legacy.
baseUrl names a folder against which non-relative import paths are tried. With "baseUrl": "./src", the import "utils/format" is looked up as ./src/utils/format before the compiler falls back to node_modules. It gives short, absolute-looking imports without ../../.. chains.
It is a legacy option. Since TypeScript 4.1 you can use paths without it, and recent compilers report baseUrl as deprecated, so a new project should prefer paths with relative targets. The compiler never rewrites the import in the output; your runtime or bundler must know the same rule.
{ "compilerOptions": { "baseUrl": "./src" } }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
{ "compilerOptions": { "baseUrl": "./src" } }
| Part | Description |
|---|---|
| Value | A path, relative to the tsconfig.json that sets it. No default (not set). |
| Lookup | A non-relative import is first tried against baseUrl, then against node_modules. |
With paths |
Targets in paths resolve against baseUrl when it is set; otherwise against the tsconfig.json folder. |
| Not affected | Relative imports (./x) never use it. |
Edge cases: an entry in paths that does not start with ./ is an error when baseUrl is not set (TS5090). baseUrl alone does not map @app/... style aliases; that is the job of paths.
Usage notes
- Runtime must agree.
tscleavesimport "utils/format"as written. Node does not know aboutbaseUrl; bundlers need an alias plugin, and Node needspackage.jsonimportsor a loader. - Shadowing. A folder named like a package hides that package (see the second example). Aliases such as
@app/*avoid the problem. - Prefer
pathswith./."paths": { "@app/*": ["./src/*"] }works withoutbaseUrl. - Editors use it for auto-imports, so a stale
baseUrlleads to odd import suggestions. - Migration. Remove it by replacing absolute-looking imports with an alias or relative paths, then drop the option.
- Monorepos. Each package gets its own
baseUrl; do not share one from a root config unless every package has the same layout.