Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{
  "compilerOptions": {
    "baseUrl": "./src"
  }
}

Try it

TypeScript How a base folder resolves a specifier

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.

TypeScript The classic pitfall

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

JSON
{ "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. tsc leaves import "utils/format" as written. Node does not know about baseUrl; bundlers need an alias plugin, and Node needs package.json imports or a loader.
  • Shadowing. A folder named like a package hides that package (see the second example). Aliases such as @app/* avoid the problem.
  • Prefer paths with ./. "paths": { "@app/*": ["./src/*"] } works without baseUrl.
  • Editors use it for auto-imports, so a stale baseUrl leads 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.