Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

Path mapping with paths and baseUrl

How TypeScript path mapping works: paths patterns, baseUrl, wildcard matching, why tsc does not rewrite aliases, and runtime options such as package imports.

Path mapping lets you import a module through an alias such as @app/utils instead of a long relative path like ../../../shared/utils. You declare aliases in tsconfig.json with the paths option, which maps an import pattern to one or more locations.

The crucial detail: paths only tells the type checker where to look. The compiler does not rewrite the specifier in the output, so import "@app/utils" is emitted unchanged and your runtime or bundler must resolve it too. Bundlers and test runners usually have their own alias settings or read paths for you; plain Node does not.

JSON
{
  "compilerOptions": {
    "paths": {
      "@app/*": ["./src/*"],
      "@config": ["./src/config/index.ts"]
    }
  }
}

Try it

TypeScript A model of paths matching

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 Aliases the runtime understands: package imports

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": "./",
    "paths": { "alias": ["location", "fallback"] }
  }
}
Option Description
paths Object from a pattern to an array of locations. A pattern may contain one *, which captures text that is substituted for the * in each location. Locations are tried in order.
baseUrl Optional. A folder against which non-relative imports resolve, and against which paths locations resolve when set. Since TypeScript 4.1 paths works without it, resolving against the tsconfig.json folder.

Errors and edge cases:

  • If nothing matches, TypeScript falls back to normal resolution and reports TS2307 when that fails too.
  • A location must point to a file TypeScript can read (.ts, .d.ts, or a folder with an index). A .js file alone needs allowJs.
  • More than one * in a pattern is an error.
  • If a paths entry matches but none of its locations exist, resolution continues with the normal lookup, so a typo in a location can go unnoticed until the import fails.

Usage notes

  • Runtime support is on you. Options: bundler aliases (Vite resolve.alias, webpack resolve.alias), Node's package.json "imports" field with # names (as shown above, and understood by TypeScript with nodenext or bundler), a loader, or a build step that rewrites paths.
  • Setting baseUrl alone makes any top-level folder importable as a bare name (import "utils/x"), which looks like a package and breaks easily. Prefer explicit paths or # imports.
  • Because of this, baseUrl is considered a legacy option and its use is discouraged in new projects.
  • In a monorepo, prefer real workspace packages and project references over paths pointing across package folders.
  • Keep aliases few and consistent; every alias is one more thing to configure in the editor, compiler, test runner, linter and bundler.
  • Declaration files emitted with declaration keep alias specifiers as written, which breaks consumers; avoid aliases in public library code.