TypeScript Path Aliases in 2026: tsconfig Paths, Bundler Resolution, and Why They Still Break at Runtime
This article was written with the assistance of AI, under human supervision and review.
Most TypeScript path alias problems stem from a fundamental misconception: developers configure tsconfig.json paths, see their editor resolve imports correctly, and assume the work is done. Then production crashes because Node.js has no idea what @/components/Button means. The TypeScript compiler never emits path-rewritten JavaScript—it only validates types using those aliases. Every runtime tool needs its own resolution configuration, and most projects ship with exactly zero of them.
The pattern teams overlook is this: path aliases are a compile-time abstraction that exists solely in TypeScript's type-checking phase. When tsc outputs JavaScript, those @/ imports stay verbatim in the emitted code. The assumption that one paths object in tsconfig.json will propagate to Vite, Webpack, esbuild, Node.js, and Jest is the reason deployments fail silently until a dynamic import executes in staging.
The correct approach requires treating path aliases as a cross-tool contract. TypeScript validates types, bundlers transform imports for browsers, and Node.js resolves modules at runtime. Each tool interprets the same logical alias through its own resolution mechanism. Configure all three, or ship broken imports.
This post covers the mechanics of TypeScript path resolution, the bundler configurations that actually work in 2026, and the production patterns that prevent runtime failures. Apply these and the "works on my machine" aliasing problem disappears.
Key Takeaways TypeScript's paths in tsconfig.json affect ONLY type-checking and editor autocomplete—emitted JavaScript retains literal alias imports that crash at runtime without bundler or loader configuration. Every tool in the build chain (Vite, Webpack, esbuild, Node.js, Jest) requires its own alias resolution setup; a single tsconfig.json never suffices for production. Post-compilation rewriting with tsc-alias works but adds build steps; runtime loaders (tsx, ts-node/esm) avoid file transformation but require consistent tooling across environments. Standardize on one alias prefix (@/ for application code, ~/ for workspace roots) and map it to a single source directory to prevent ambiguous overlapping patterns that break in bundlers with first-match semantics.
TypeScript's path alias system exists as a convenience layer in the type-checker. When developers write import { Button } from '@/components/Button', the compiler consults the paths mapping in tsconfig.json to locate the corresponding .ts file for type validation. This mechanism affects two things: editor IntelliSense and the type-checking pass. It affects zero things about JavaScript output.
The tsc compiler emits JavaScript with the exact import specifier the developer wrote. If the source reads '@/components/Button', the output JavaScript will contain '@/components/Button'. TypeScript does not rewrite import paths to relative or absolute forms. The assumption that paths triggers automatic resolution transformations is the first failure mode.
This distinction is critical. TypeScript provides type safety during development but delegates module resolution to the JavaScript runtime or bundler. A project that compiles successfully with tsc --noEmit can still crash instantly when Node.js executes the output, because Node's resolver has no knowledge of TypeScript's paths configuration.
The implication here is that path aliases introduce a coordination problem. Every tool that processes the codebase—whether at compile time, bundle time, or runtime—must understand the same alias-to-path mapping. The TypeScript compiler's validation is necessary but insufficient for working software.
The paths object in tsconfig.json establishes the canonical mapping that all other tools should mirror. The configuration accepts glob patterns and supports wildcard matches, but pragmatic teams stick to exact prefix mappings with trailing slashes.
The baseUrl field sets the root for relative path resolution. Without it, TypeScript interprets paths entries as invalid. The @/ wildcard pattern maps any import starting with @/ to the corresponding path under src/. The specialized @components/ and @lib/ aliases provide shorter notation for frequently accessed directories.
This setup works for editor autocomplete and type-checking. Developers see green squiggles disappear and assume the problem is solved. The failure mode emerges when they run the compiled JavaScript directly with Node.js or deploy a server-side build. Node's module resolver follows the ECMAScript specification, which knows nothing about @ prefixes. The import fails immediately.
Teams often add a catch-all pattern as a last-resort fallback. This pattern creates more problems than it solves because it makes every unresolved import potentially valid, masking typos and incorrect specifiers during development. When an import should fail, it silently resolves to an unexpected file, and the error surfaces hours later in a failing test. Avoid catch-all wildcards.
The other common mistake is overlapping patterns. Configuring both @lib/ and @/ where @lib/ maps to src/lib/ and @/ maps to src/ creates ambiguity. Some bundlers and loaders use first-match semantics, others use longest-prefix-match. The behavior diverges across tools, and imports that resolve correctly in Vite fail in Jest. Use non-overlapping prefixes or commit to a single canonical alias per directory tree.
TypeScript's paths configuration lives in the type system. Bundlers operate on JavaScript module graphs. These are separate concerns that happen to use similar syntax but have no automatic synchronization mechanism. The gap between them is where runtime failures occur.
When Vite encounters import { Button } from '@/components/Button' in a source file, it invokes its own module resolution algorithm. By default, that algorithm checks nodemodules, relative paths, and package exports. It does not parse tsconfig.json. The import fails unless Vite has an explicit alias configuration that mirrors the TypeScript setup.