TypeScript Reference ยท tsconfig: Language, Modules and Emit Options
TypeScript paths option
Reference for the tsconfig paths option: alias patterns with one wildcard, fallback lists, match priority, errors, and why tsc does not rewrite imports.
paths maps import specifiers to file locations. Each key is a pattern (optionally with one *), and each value is a list of places to look. With "@app/*": ["./src/*"], the import "@app/models/user" is found at ./src/models/user.
The option only changes how the compiler finds types. It does not touch the emitted JavaScript, so the alias must also be understood by whatever runs the code: a bundler alias, a Node imports map or a test runner setting.
{ "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": { "paths": { "<pattern>": ["<location>", "..."] } } }
| Part | Description |
|---|---|
| Key | A module specifier pattern with at most one *. An exact key beats a wildcard key; among wildcards the longest prefix wins. |
| Value | A non-empty array of locations. They are tried in order and may contain one *, replaced by the text the key's * matched. |
| Base | Locations resolve against baseUrl if set, otherwise against the folder of the tsconfig.json that defines paths. |
Edge cases: without baseUrl, a location that does not start with ./ or ../ is an error (TS5090). Relative imports are never remapped. Locations may point at files with or without an extension, and at folders with an index file.
Usage notes
- No rewriting.
tscemitsimport "@app/models/user"unchanged. At run time you need the same alias elsewhere (package.jsonimports, a bundler alias, or a tool such astsc-alias). - Prefix with a symbol.
@app/*or#app/*cannot be confused with an npm package, unlikeutils/*. - Fallbacks are useful for generated code: look in
./src/*first, then./generated/*. - Extends. A
pathsvalue in a child config replaces the parent's whole object; locations are resolved relative to the config that wrote them (orbaseUrl). - Type-only effect. If the runtime cannot resolve the alias, the program type-checks and then crashes with a module-not-found error.
- Monorepos. Map workspace packages to their source folders so the editor jumps to
.tsfiles instead of built.d.tsfiles.