Path Aliases
In this page:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@alias/*": ["src/path/*"]
}
}
}baseUrl
baseUrl establishes the base directory TypeScript uses when resolving non-relative module names, turning imports like "utils/helpers" into lookups rooted at that directory instead of requiring "../../utils/helpers".
Example: baseUrl
// tsconfig.json
// { "compilerOptions": { "baseUrl": "./src" } }
// import { helper } from "utils/helper"; // resolved from src/
console.log("baseUrl roots non-relative imports at a chosen directory");Defining a Path Alias
The paths option maps an alias pattern to one or more actual project locations, so you can write a short, stable import path instead of a long relative one that breaks every time you move a file.
Example: Defining a Path Alias
// tsconfig.json
// { "compilerOptions": { "baseUrl": ".", "paths": { "@utils/*": ["src/utils/*"] } } }
// import { helper } from "@utils/helper";
console.log("paths maps a short alias to a real project location");Using Aliases in Imports
Once configured, TypeScript understands aliased import paths during both type checking and editor autocomplete, so the alias behaves just like a real module path as far as the compiler is concerned.
Example: Using Aliases in Imports
// import { formatDate } from "@utils/date";
console.log("Aliased imports work in both type checking and editor autocomplete");Aliases with Multiple Targets
A single alias can point at multiple target patterns, and TypeScript tries each configured substitution in order until one resolves — useful when a symbol might live in more than one possible location.
Example: Aliases with Multiple Targets
// tsconfig.json
// { "compilerOptions": { "paths": { "@shared/*": ["packages/a/*", "packages/b/*"] } } }
console.log("A single alias can try multiple target locations in order");Runtime Considerations
TypeScript's paths option only affects how TypeScript itself resolves modules during type checking — it doesn't rewrite the actual runtime import paths, so your bundler or runtime also needs its own alias configuration to match.
Example: Runtime Considerations
// tsconfig.json's paths only affects TypeScript's own type checking --
// a bundler (webpack, Vite) needs its own matching alias config to run.
console.log("paths doesn't rewrite runtime import paths on its own");- Adding
pathsintsconfig.jsonand expecting Node to resolve the alias at runtime, whentscdoes not rewrite them and a bundler or runtime tool must also know them. - Writing
"@utils/*": "src/utils/*"with a string instead of an array of paths. - Forgetting the
/*on both the alias and the target, so@utils/helperdoes not match.
Chapter Quiz — Complete all 7 topics to unlock
0/7 topics done
Complete these topics first: