TypeScript Path Alias Guide: tsconfig Paths, Bundlers, and Runtime Fixes

Overview

If you want a short version, here it is: compilerOptions.paths helps TypeScript understand module names during type checking, but it does not automatically teach every other tool in your stack how to resolve those same aliases. That gap is the source of most “typescript alias not working” problems.

A typical setup looks like this:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

With that configuration, imports like these become valid to TypeScript:

import { Button } from '@components/Button';
import { formatUser } from '@/utils/formatUser';

That improves readability and reduces long relative paths such as ../../../utils/formatUser. But path mapping in TypeScript is only one layer. Depending on your setup, you may also need to align:

• your bundler or framework resolver
• your runtime environment
• your test runner
• your linter and editor settings
• your monorepo package boundaries

Before diving into scenario-based checklists, keep these principles in mind:

• TypeScript is not your runtime. It checks types and can emit JavaScript, but it does not rewrite every import path in a way that all runtimes understand.
• Aliases are best for app-level ergonomics. For reusable libraries or packages, real package boundaries are often clearer than deep alias systems.
• Keep aliases few and predictable. A small set of stable roots is easier to maintain than many overlapping shortcuts.

If you are still getting comfortable with project setup, this article pairs well with TypeScript for Beginners: A Step-by-Step Learning Path That Stays Current and TypeScript Build Tools Compared: tsc vs esbuild vs swc vs tsup vs vite.

Checklist by scenario

Use this section as a practical reference before you change tooling or debug broken imports.

Scenario 1: Plain TypeScript project using tsc

What you get: type-aware alias resolution in the compiler and editor. What you may not get: working runtime imports after build, especially in Node.js.

Checklist:

• Set baseUrl explicitly, usually to . or the project root.
• Define paths with clear patterns.
• Make sure the aliased directories actually match your source layout.
• Confirm your emitted JavaScript still points to something the runtime understands.

Example:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    "outDir": "dist"
  },
  "include": ["src"]
}

Important: if you compile with tsc and run the emitted files directly with Node, aliases may still fail unless your runtime has its own resolution support or your build step rewrites imports.

Scenario 2: Vite, webpack, Rollup, or similar bundler

Bundlers usually need their own alias configuration. Even if TypeScript accepts the import, the bundler may not.

Checklist:

• Keep tsconfig.json as the source of truth for editor and compiler resolution.
• Mirror the same aliases in the bundler config, or use a plugin that reads them.
• Restart the dev server after changing alias settings.
• Check whether the bundler resolves from project root, config file location, or package root in a monorepo.

Generic example:

// bundler config example
resolve: {
  alias: {
    '@': '/src'
  }
}

If you use a plugin-based setup, verify that it reads the same tsconfig file you are editing. In multi-config projects, this is a common source of drift.

For a broader comparison of tool behavior, see TypeScript Build Tools Compared: tsc vs esbuild vs swc vs tsup vs vite.

Scenario 3: Next.js or framework-managed projects

Frameworks often support baseUrl and paths out of the box, but you should still validate behavior rather than assume every environment matches local development.

Checklist:

• Define aliases in tsconfig.json or the framework-recognized config file.
• Confirm the framework version and build mode support your chosen alias pattern.
• Test local development, production build, and any server-side code paths separately.
• Avoid using aliases to cross intended app boundaries, such as importing server-only code into client components.

Framework support can feel seamless until you add tests, storybook, edge runtimes, or custom scripts. At that point, you often need to configure those tools separately.

Scenario 4: Node.js runtime with ts-node, direct TypeScript execution, or custom loaders

This is one of the most error-prone cases. TypeScript understands the alias, but the runtime still needs to know what @/foo means.

Checklist:

• Decide whether the runtime will resolve aliases directly or whether you will rewrite imports during build.
• If running TypeScript directly, make sure your execution tool supports reading tsconfig paths or has a companion resolver.
• If emitting JavaScript first, inspect the output and verify imports are still valid for your runtime.
• Be extra careful when switching between ESM and CommonJS, because resolution rules differ.

A useful mental model is this: the compiler can validate the path, but your runtime must still execute it. Those are separate concerns.

Scenario 5: Jest, Vitest, or other test runners

Tests often break first because test runners have their own module resolution layer.

Checklist:

• Add matching alias rules in the test config.
• Make sure mocks and setup files use the same conventions as application code.
• Check that coverage tooling points at source files correctly after alias resolution.
• Run one focused test file after changes instead of relying only on IDE feedback.

If your app builds but tests fail with module-not-found errors, this usually means the test runner was never told about your aliases.

Scenario 6: ESLint, editor tooling, and import sorting

Sometimes the code runs, but the linter reports unresolved imports or auto-import chooses the wrong path style.

Checklist:

• Ensure ESLint import resolution matches your TypeScript setup.
• Confirm your editor is using the project TypeScript version, not a global fallback.
• Check whether import sorting rules treat aliases as internal modules or external packages.
• Standardize whether your team prefers alias imports, relative imports, or a mix by folder depth.

For related setup guidance, see ESLint and TypeScript Setup Guide: Flat Config, Rules, and Performance Tips.

Scenario 7: Monorepos and shared code

Aliases can be helpful in monorepos, but they can also hide package boundaries and encourage accidental coupling.

Checklist:

• Decide whether an import should use a path alias or a workspace package name.
• Use aliases mainly for intra-app paths, not as a substitute for real packages.
• Check each package’s local tsconfig inheritance and resolution context.
• Confirm build tools, test tools, and editors are all reading the intended config layer.

If your monorepo is growing, package names are often a better long-term contract than broad root aliases. For deeper structure decisions, see TypeScript Monorepo Guide: Project References, Path Aliases, and Package Boundaries.

What to double-check

When aliases stop working, the fix is often small. The hard part is knowing where to look. Use this short debugging checklist in order.

1. Is baseUrl set?
   Without it, paths may not behave the way you expect.
2. Do the path patterns match real folders?
   A typo like src/component/* instead of src/components/* can be easy to miss.
3. Are you editing the correct tsconfig file?
   Many projects have tsconfig.json, tsconfig.build.json, test configs, and framework-specific variants.
4. Did you restart the relevant process?
   The TypeScript server, dev server, and test runner may all cache old config.
5. Does the bundler or runtime also know the alias?
   TypeScript support alone is not enough.
6. Are file extensions, ESM settings, or module resolution modes involved?
   An alias issue may really be a module-format issue.
7. Are you mixing root aliases and package imports in confusing ways?
   For example, @/utils may look too similar to a scoped package import.
8. Did generated code or output directories move?
   If outDir, build targets, or source roots changed, alias mappings may now point at the wrong layer.

It also helps to inspect one concrete failing import instead of reasoning abstractly about the whole setup. Pick a single file, trace how TypeScript resolves it, then trace how the bundler, runtime, or test runner resolves the same string.

As a best practice, keep aliases boring. A single root alias like @/* or a small set such as @components/* and @lib/* is usually enough. Once alias rules become a mini language, debugging costs rise quickly.

Common mistakes

Most path alias problems come from a few recurring patterns.

1. Treating paths as a complete runtime solution

This is the main misconception. tsconfig path mapping is primarily a compile-time and editor-time feature. Unless another tool participates, your runtime may still fail.

2. Creating aliases that hide architectural problems

Aliases can make imports look clean while masking poor boundaries. If everything can import everything through a short prefix, it becomes harder to see dependency direction. In larger codebases, clear module ownership matters more than pretty import strings.

3. Overlapping alias patterns

These are harder to reason about:

{
  "paths": {
    "@/*": ["src/*"],
    "@utils/*": ["src/shared/utils/*"],
    "@shared/*": ["src/shared/*"]
  }
}

Overlaps can make imports inconsistent across the codebase. Prefer a simpler scheme with obvious intent.

4. Using aliases where package imports are clearer

In monorepos, importing shared code through a workspace package name is often more explicit than reaching into another package with a root alias. If code is meant to be consumed across boundaries, package it that way.

5. Forgetting non-app tools

Developers often update the app bundler but forget tests, scripts, code generation tools, or linting. If a tool parses imports, it may need to understand aliases too.

6. Switching module systems without retesting alias behavior

Moving from CommonJS to ESM, changing moduleResolution, or adopting a new build tool can surface old assumptions. Re-run your alias checklist any time module handling changes.

7. Relying on aliases in examples, configs, or snippets without documenting them

Aliases are part of project infrastructure. If teammates copy code from one area to another and the import style suddenly breaks, the issue may be missing project context, not the import itself.

When you want safer config patterns in general, especially where TypeScript should validate shape without widening too far, How to Use satisfies in TypeScript with Safer Object and Config Patterns is a useful companion read.

When to revisit

Path alias setup is worth revisiting whenever your tooling or project boundaries change. This is not a one-time configuration task. It is a small piece of system design that should be checked again when the underlying environment shifts.

Revisit your alias strategy when:

• you adopt a new bundler or build pipeline
• you move from JavaScript to TypeScript during migration
• you switch between ESM and CommonJS
• you add a test runner, storybook, or code generation step
• you split an app into packages or a monorepo
• you introduce server-only and client-only code boundaries
• your team starts debating import conventions in code review

A practical review routine:

1. List every tool that resolves imports: compiler, bundler, runtime, tests, linter, editor.
2. Check which config file each tool reads.
3. Verify whether aliases are defined once and reused, or duplicated manually.
4. Run one compile, one local dev session, one production build, and one test command.
5. Decide whether each alias still serves a clear purpose.
6. Remove aliases that no longer improve clarity.

If you are planning broader project maintenance, this review fits naturally into tooling updates and seasonal cleanup cycles. It is especially useful before refactors, framework upgrades, or monorepo restructuring.

A good final rule is simple: use TypeScript path aliases to reduce friction, not to create a hidden dependency map. Keep the config small, align every tool that resolves imports, and test the actual environment that will run your code. That approach turns aliases from a recurring annoyance into a stable, reusable part of your TypeScript project structure.