Source-root imports
A project wants short, non-relative imports rooted at its source directory.
TypeScript · Const
baseUrl
Sets the directory TypeScript uses to resolve bare module specifiers. It can make imports such as "utils/date" resolve from a configured project directory before node_modules.
How it works
Set baseUrl in compilerOptions to establish a directory for resolving bare module specifiers such as "utils/date". TypeScript checks that directory before node_modules, but baseUrl affects compiler resolution only; the runtime or bundler must independently understand the same import mapping.
Syntax
{"compilerOptions":{"baseUrl":"./src"}}Parameters
| Name | Type | Description |
|---|---|---|
baseUrl | string | Directory used as the starting point for resolving bare module specifiers; relative values are based on tsconfig.json. |
Returns
No runtime value; this tsconfig compiler option changes TypeScript's module-resolution behavior.
Key points
- baseUrl establishes the directory TypeScript uses when resolving non-relative imports.
- A relative value is interpreted from the directory containing tsconfig.json.
- A matching file under baseUrl takes precedence over a corresponding node_modules lookup.
- paths can be used without baseUrl; its mappings otherwise resolve relative to the tsconfig file.
Common mistakes
- The option is primarily intended for AMD browser loaders and is discouraged as a general-purpose alias mechanism.
- Do not add baseUrl solely to enable paths mappings in modern TypeScript.
Example: Resolve a bare import from a project directory
// tsconfig.json
// {
// "compilerOptions": { "baseUrl": "./src" }
// }
import { formatDate } from "utils/date";
console.log(formatDate(new Date()));With baseUrl set to ./src, the bare import resolves from the project's src directory.
When to use it
AMD module loading
An AMD browser application loads modules from one deployment directory.
Alias mapping foundation
A project uses paths mappings whose targets should be relative to a shared base directory.
Related
pathsmoduleResolutionrootDirs