Skip to content
Tutorials Center
My learning

Topics

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.

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

Try it

TypeScript Matching a pattern with a wildcard

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 Longest prefix wins

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": { "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. tsc emits import "@app/models/user" unchanged. At run time you need the same alias elsewhere (package.json imports, a bundler alias, or a tool such as tsc-alias).
  • Prefix with a symbol. @app/* or #app/* cannot be confused with an npm package, unlike utils/*.
  • Fallbacks are useful for generated code: look in ./src/* first, then ./generated/*.
  • Extends. A paths value in a child config replaces the parent's whole object; locations are resolved relative to the config that wrote them (or baseUrl).
  • 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 .ts files instead of built .d.ts files.