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.
problem flow showing import failing at runtime
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.
solution flow with synchronized tooling
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.
paths
in tsconfig.json
affect ONLY type-checking and editor autocomplete—emitted JavaScript retains literal alias imports that crash at runtime without bundler or configuration.tsconfig.json
never suffices for production.tsc-alias
works but adds build steps; runtime s (tsx
, ts-node/esm
) avoid file transformation but require consistent tooling across environments.@/
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.
TypeScript compilation flow showing path alias handling
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.
// tsconfig.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/components/*"],
"@lib/*": ["src/lib/*"]
}
}
}
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 s 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 node_modules
, 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.
bundler resolution flow showing configuration gap
The same disconnect affects Webpack, esbuild, Rollup, and every other bundling tool. Each has a different configuration syntax for alias resolution. Webpack uses resolve.alias
, esbuild uses a plugin, and Vite uses resolve.alias
but with different path handling than Webpack. Developers who copy-paste a Webpack alias config into a Vite project often see builds succeed locally but fail in CI where paths differ.
Node.js itself has no native path alias support. The --experimental-
flag in recent versions allows custom resolution hooks, but this is an opt-in feature that requires shipping a script with the application. For server-side TypeScript projects deployed to Node, the standard practice is either to use a runtime transpiler like tsx
that understands tsconfig.json
paths, or to rewrite imports during a build step with a tool like tsc-alias
.
The failure mode here is subtle but expensive. A frontend project might work perfectly in development with Vite's alias resolution, but when the same codebase gets reused for a server-side rendering entry point running in Node, every @/
import crashes because Node lacks the configuration. The team adds tsx
to start scripts, but then CI runs raw Node and the deployment fails. This cycle repeats until every execution environment—dev, test, build, deploy—has explicit alias handling.
Each bundler provides its own alias resolution API. The syntax differs but the principle is identical: map a prefix to a filesystem path before the resolver checks node_modules
. The configuration must exactly match the TypeScript paths
mapping to avoid drift.
Vite uses resolve.alias
in vite.config.ts
. The value can be an object or an array of { find, replacement }
entries. For glob patterns, use the array form.
// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';
export default defineConfig({
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
'@components': path.resolve(__dirname, './src/components'),
'@lib': path.resolve(__dirname, './src/lib'),
},
},
});
Webpack uses resolve.alias
in webpack.config.js
. The trailing $
in the key makes the alias exact-match, but for directory mappings, omit it.
// webpack.config.js
const path = require('path');
module.exports = {
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
'@components': path.resolve(__dirname, 'src/components'),
'@lib': path.resolve(__dirname, 'src/lib'),
},
},
};
esbuild requires a plugin for path alias support because its core API has no built-in alias resolution. The esbuild-plugin-alias
package provides the functionality.
// build.mjs
import esbuild from 'esbuild';
import alias from 'esbuild-plugin-alias';
import path from 'path';
esbuild.build({
entryPoints: ['src/index.ts'],
bundle: true,
outdir: 'dist',
plugins: [
alias({
'@': path.resolve('./src'),
'@components': path.resolve('./src/components'),
'@lib': path.resolve('./src/lib'),
}),
],
});
Node.js with tsx
or ts-node
reads tsconfig.json
paths automatically. No additional configuration is needed if the paths
object is correctly defined. For production deployments that run compiled JavaScript without a TypeScript runtime, use tsc-alias
as a post-compilation step or set up a custom .
The pattern here is duplication. The same alias mapping exists in tsconfig.json
for TypeScript, in vite.config.ts
for Vite, and potentially in a Jest config for testing. When a new alias is added, developers must update all three files. The synchronization burden is manual and error-prone. Teams that skip one configuration file inevitably discover the gap during a deployment or in a flaky test suite.
Two strategies handle path aliases in compiled rewriting imports during the build or resolving them at runtime. Each approach has tradeoffs that affect deployment complexity and debugging clarity.
tsc-alias is a post-compilation tool that rewrites alias imports to relative paths after tsc
emits JavaScript. The workflow is: compile TypeScript with tsc
, then run tsc-alias
to transform the output. This produces plain JavaScript with no special s required at runtime.
comparison of tsc-alias vs runtime resolution
The advantage of tsc-alias
is portability. The output JavaScript runs in any Node environment without flags or custom s. The disadvantage is the extra build step. Every compilation requires two commands, and source maps can become stale if the rewriting logic changes file paths unexpectedly. Debugging a rewritten import that resolves to the wrong file is harder than debugging a runtime resolution failure that points to the original source line.
Runtime resolution with tsx
or ts-node/esm
keeps the original TypeScript files with alias imports intact and resolves them during execution. The reads tsconfig.json
paths and transforms imports on the fly. This approach eliminates the build step but requires every environment—dev, test, production—to use the same .
The failure mode here is environment drift. Developers run tsx src/index.ts
locally, tests run with jest
configured to use ts-jest
, and production deploys a Docker image running node dist/index.js
after a tsc
build. The aliases work in dev and test but crash in production because no is present. The team either adds tsx
to the production start script (reintroducing runtime transpilation overhead) or rewrites the production build to use tsc-alias
.
The choice depends on deployment constraints. For serverless functions with cold-start sensitivity, pre-rewriting imports with tsc-alias
avoids the transpilation cost on every invocation. For long-running Node processes where startup time is irrelevant, runtime resolution simplifies the build pipeline. There is no universal right answer, but consistency across environments is non-negotiable.
The production pattern that eliminates alias-related failures is dual configuration with validation. Configure path aliases in both tsconfig.json
and the bundler, then add a pre-commit hook that verifies the two stay synchronized.
production workflow with validation
The validation script reads both configurations and asserts they define identical alias-to-path mappings. This prevents the common scenario where a developer adds @hooks/*
to tsconfig.json
but forgets to update vite.config.ts
, causing imports to work locally but fail in the production build.
A more robust approach uses a shared configuration file that both TypeScript and the bundler import. Define aliases once in a paths.config.js
file, then consume it in tsconfig.json
via a build script that generates the final config, and import it directly in the bundler.
// paths.config.js
const path = require('path');
const aliases = {
'@': './src',
'@components': './src/components',
'@lib': './src/lib',
};
// For bundler use
exports.resolveAliases = Object.fromEntries(
Object.entries(aliases).map(([key, value]) => [
key,
path.resolve(__dirname, value),
])
);
// For tsconfig.json generation
exports.tsconfigPaths = Object.fromEntries(
Object.entries(aliases).map(([key, value]) => [`${key}/*`, [`${value}/*`]])
);
This eliminates duplication but introduces a build-time dependency. The tsconfig.json
file is no longer hand-editable JSON—it must be generated from the shared source. For teams already using complex build pipelines, this tradeoff is acceptable. For smaller projects, the validation script approach is simpler.
The other production requirement is consistent alias naming conventions. Use @/
for application source code and reserve ~/
for workspace-root paths in monorepos. Do not mix both styles in the same project. Do not use abbreviations like @c/
for components—clarity beats brevity when onboarding new engineers or debugging imports six months later.
Finally, avoid deep alias hierarchies. Configuring @components/atoms/*
, @components/molecules/*
, and @components/organisms/*
as separate aliases creates maintenance overhead with no benefit. A single @components/*
alias with subdirectory imports is sufficient and reduces the configuration surface area.
VSCode uses the TypeScript language server, which reads tsconfig.json
paths for IntelliSense and type-checking. The compiled JavaScript output retains literal alias imports that Node.js cannot resolve without a or bundler configuration. Configure your runtime tool to match the tsconfig.json
aliases.
Use tsc-alias
if you need portable JavaScript output that runs in any Node environment without extra flags. Use tsx
or similar s if you control the deployment environment and want to skip the rewriting build step. The choice depends on deployment constraints, not code quality.
Yes, but define aliases at the workspace root in a shared tsconfig.base.json
and extend it in each package's tsconfig.json
. Configure each package's bundler separately to resolve aliases relative to that package's root. Avoid aliasing across package boundaries—use workspace protocol imports instead.
The code will type-check and build successfully, but runtime imports will fail with "module not found" errors. This breaks production deployments and is the most common alias misconfiguration. Use a validation script or shared config file to prevent drift between tsconfig.json
and bundler settings.
TypeScript's type-checking with aliases has negligible overhead. Bundlers resolve aliases during the graph-building phase with the same cost as normal imports. Runtime s like tsx
add transpilation overhead on every module load, but this is unrelated to aliases specifically—it affects all TypeScript execution.
Path aliases solve import sprawl, but only when configured correctly across every tool in the build chain. The pattern that works at scale is: define aliases once in tsconfig.json
, mirror them exactly in every bundler and test runner, and validate synchronization with automated checks. Teams that skip bundler configuration or assume TypeScript's paths
propagate to runtime tools ship broken deployments.
The migration strategy for existing projects is incremental. Add one alias, configure it in all tools, deploy successfully, then add the next. Do not bulk-migrate dozens of imports at once—every alias introduces a new failure point until its bundler config is verified in production. Start with high-traffic directories like @components
or @lib
, validate the resolver behavior in CI, then expand coverage.
That covers the essential patterns for TypeScript path aliases in 2026. Configure TypeScript, configure your bundler, configure your runtime, verify they match, and the "works on my machine" aliasing problem disappears. Apply these in production and the difference will be immediate.