TypeScript path aliases can make imports shorter and project structure clearer, but compilerOptions.paths only teaches TypeScript how to resolve source files. This checklist shows how to align the editor, test runner, bundler, framework, declaration build, and production runtime so aliases do not work in one environment and fail in another.
Overview
A relative import such as ../../shared/date describes where a file is located. An alias such as @shared/date describes a stable project concept instead. That distinction is useful in large TypeScript applications, especially when folders move or when several features share infrastructure.
A typical configuration looks like this:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@shared/*": ["src/shared/*"]
}
}
}
baseUrl establishes the reference point for non-relative paths, while each paths entry maps an import pattern to one or more source locations. The exact location of tsconfig.json matters: the paths are interpreted relative to the configuration file that defines them.
The important limitation is that TypeScript path aliases are usually compile-time and tooling configuration. The TypeScript compiler can type-check @/components/Button, but it does not automatically rewrite that import into a relative path in emitted JavaScript. Every tool that resolves modules must either understand the alias directly or receive an equivalent mapping.
Before adding aliases, decide whether the project needs them. A small application may be easier to maintain with relative imports. Aliases become more valuable when imports regularly cross several directory levels, when a stable source boundary matters, or when a monorepo has clearly defined packages. Avoid an alias for every folder; a short list of purposeful boundaries is easier to document and migrate.
Checklist by scenario
1. Configure TypeScript and the editor
- Choose a single authoritative
tsconfigfor the application, or document which project configuration owns each alias. - Set
baseUrlandpathsusing paths that are relative to that configuration file. - Use a consistent prefix such as
@/or~rather than ambiguous names that could collide with installed packages. - Restart the TypeScript language service after changing configuration if the editor does not immediately recognize the new imports.
- Run the compiler with the same project file used by CI, for example
tsc --noEmit -p tsconfig.json.
Keep application and build configurations separate when necessary. A common pattern is a base configuration containing shared compiler settings and an application configuration that adds source aliases. Check that the build, editor, and test command all extend or reference the intended file rather than a neighboring configuration.
2. Align the bundler or framework
Bundlers must resolve aliases while building browser or server bundles. Many modern frameworks can read TypeScript path mappings, but this should be verified against the framework's current configuration behavior rather than assumed. If automatic support is absent or incomplete, define the same aliases in the bundler configuration.
- Vite and tools built around it: configure aliases in the Vite configuration or use the project's supported TypeScript-path integration. Test both development and production builds.
- Webpack: map the alias under
resolve.alias, or use a maintained integration that reads the relevanttsconfig. Confirm that the alias target is expressed in a format Webpack can resolve. - Next.js: place the mappings in the configuration file used by the application and verify client compilation, server compilation, and tests separately. A successful editor lookup does not prove that every Next.js execution path uses the same resolver.
- Other frameworks: find the framework's module-resolution configuration and reproduce the mapping there. Do not assume that a TypeScript-aware plugin also configures the test runner or production server.
Prefer one source of truth where the toolchain supports it. When aliases must be repeated, add a small comment or documentation note explaining which file is authoritative and how the other configuration is kept synchronized.
3. Configure the test runner
Test runners commonly use their own resolver, which is why “TypeScript aliases not working” often appears only in tests. For Jest, map the alias with moduleNameMapper. A wildcard alias usually needs a regular expression and a replacement pointing to the project root, for example:
moduleNameMapper: {
'^@/(.*)$': '<rootDir>/src/$1',
'^@shared/(.*)$': '<rootDir>/src/shared/$1'
}
For Vitest, configure aliases through its Vite-compatible settings or the supported TypeScript-path integration. Other runners may use a resolver option, a loader, or a separate configuration file. Check the test command's actual project root, especially in a monorepo, and run at least one test that imports through every important alias family.
Also test setup files, mocks, coverage instrumentation, and snapshots. A test body may resolve correctly while a global setup file or mock factory still uses a resolver that does not know the alias.
4. Make the runtime understand the import
If emitted JavaScript still contains @/..., Node.js or another runtime must understand that specifier. TypeScript's paths setting alone does not provide that runtime behavior. You have three broad options:
- Use a bundler that resolves and rewrites the alias during the build.
- Add a runtime resolver or loader supported by the application’s module system and deployment command.
- Use package-based imports, such as a package's
exportsor runtime-supportedimportsconfiguration, when the boundary should exist in built code rather than only in source.
Test the exact production artifact, not only TypeScript source. Build the project, inspect representative emitted imports, and execute the same start command used in deployment. This catches broken JavaScript that a type check cannot detect.
5. Handle monorepos and package boundaries
In a monorepo, a root alias that points directly into another package's source can bypass that package's public API, build output, and declaration boundaries. That may be acceptable for a single application, but it is usually a warning sign for reusable packages.
For package-to-package imports, prefer the package name and configure each package's main, module, types, or exports fields according to its module format. Use path aliases primarily for internal application structure. When publishing a package, validate declarations and emitted JavaScript independently; an alias that works in the repository may not exist for consumers.
Compatibility matrix
| Environment | What must be configured | Verification |
|---|---|---|
| TypeScript compiler and editor | baseUrl and paths in the correct project file | Editor navigation and tsc --noEmit |
| Vite-based tooling | Vite alias support or a TypeScript-path integration | Development server and production build |
| Webpack | resolve.alias or an equivalent integration | Bundled output and source-map debugging |
| Jest | moduleNameMapper and the correct root directory | Unit test, setup file, and mock import |
| Vitest | Vite-compatible resolver configuration | Test command from the repository root and package directory |
| Node.js runtime | Bundled output, supported loader, or package-based imports | Run the built artifact with the deployment command |
| Published package | Public package entry points and declaration paths | Install into a clean consumer project |
What to double-check
- Configuration scope: confirm whether the command uses the root, application, package, or test-specific
tsconfig. - Wildcard shape:
@/*and@shared/*are different patterns. The replacement must preserve the captured portion. - Case sensitivity: an import that works on a case-insensitive local filesystem can fail in a case-sensitive CI or deployment environment.
- Duplicate modules: importing the same file once through a relative path and once through an alias can produce confusing identity issues, especially with singletons, context objects, and mocked modules. Standardize one import style per boundary.
- Declaration output: inspect generated
.d.tsfiles for unresolved aliases when building libraries. Consumers cannot resolve a private application alias that was accidentally published. - ESM and CommonJS behavior: confirm that the chosen runtime and package configuration agree on module format. Alias configuration does not remove the separate requirements of each module system.
- Project references: in larger builds, check that referenced projects expose the files and declarations the importing project expects instead of reaching into private source folders.
A useful diagnostic sequence is to test in this order: editor navigation, TypeScript type-checking, test execution, development server, production build, and finally the built runtime. The first failing layer usually identifies which resolver has not been configured.
Common mistakes
Assuming paths rewrites JavaScript
This is the most common error. If a compiler emits an alias unchanged, the runtime still needs a way to resolve it. Inspect the output directory instead of inferring behavior from a successful type check.
Copying a Jest mapping into another tool
Jest regular expressions, Vite aliases, Webpack paths, and Node package imports have different syntax and semantics. Translate the mapping for each resolver; do not paste configuration blindly.
Using aliases to hide package architecture
An alias such as @everything/* makes any internal folder appear public. Prefer aliases that communicate boundaries, such as @features/* or @shared/*, and enforce allowed dependency direction with linting or project structure.
Testing only the editor
Autocomplete is useful, but it proves only that the language service found the file. CI, tests, bundling, declarations, and production execution each require their own check.
Pointing a published package at source aliases
Application aliases and package entry points solve different problems. Follow a package build and export strategy that gives consumers resolvable JavaScript and declarations; see the guidance on publishing TypeScript packages for the broader release checklist.
When to revisit
Revisit this configuration whenever the underlying module-resolution workflow changes: switching bundlers, changing test runners, enabling a different Node.js module format, introducing a monorepo package, changing the deployment command, or upgrading a framework integration. It is also worth reviewing before a seasonal planning cycle or a larger refactor, when aliases may be used to create new boundaries.
Use this practical pre-merge checklist:
- Document each alias and its intended boundary.
- Confirm the editor and TypeScript compiler use the expected
tsconfig. - Run a type check and a test that imports through each important alias.
- Build the application with the production configuration.
- Inspect emitted imports and declaration files.
- Start the built artifact using the real deployment command.
- For packages, test from a clean consumer project rather than only from the monorepo.
If any step fails, fix the resolver at that layer instead of adding another unrelated alias plugin. A small, documented mapping that every tool understands is more maintainable than a large collection of special cases.