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.
{ "compilerOptions": { "paths": { "@app/*": ["./src/*"], "@config": ["./src/config/index.ts"] } } }
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": "./", "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.jsfile alone needsallowJs. - More than one
*in a pattern is an error. - If a
pathsentry 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, webpackresolve.alias), Node'spackage.json"imports"field with#names (as shown above, and understood by TypeScript withnodenextorbundler), a loader, or a build step that rewrites paths. - Setting
baseUrlalone makes any top-level folder importable as a bare name (import "utils/x"), which looks like a package and breaks easily. Prefer explicitpathsor#imports. - Because of this,
baseUrlis considered a legacy option and its use is discouraged in new projects. - In a monorepo, prefer real workspace packages and project references over
pathspointing 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
declarationkeep alias specifiers as written, which breaks consumers; avoid aliases in public library code.
Related
- paths, baseUrl, Module resolution, package.json exports
- Lessons: Modules, Large projects