tsconfig paths aliases fail at runtime after emit despite passing type-check
0 reputation · 22 Feb 2025, 19:22 UTC
TypeScript path mappings declared via baseUrl and paths in tsconfig.json are compile-time module-resolution aliases. Local type-checking and development tools can resolve them, but emitted JavaScript typically retains the original import specifiers unchanged, creating a gap between local success and production runtime behavior.
The unresolved decision is that TypeScript provides no built-in compiler option to rewrite these aliases into relative or absolute paths during emit. Whether aliases work after compilation depends entirely on the production runtime or bundler configuration, such as webpack, Vite, esbuild, or Node.js. Behavior can also diverge under moduleResolution node16 or nodenext because package.json exports fields influence resolution independently of paths. Because resolution rules vary across TypeScript versions, any diagnosis should account for the exact compiler version and module settings in both environments.
Which combinations of module and moduleResolution are expected to preserve alias behavior through emit for Node.js ESM? How can teams confirm that a production bundler mirrors tsconfig paths without maintaining a separate alias list? Is there a documented, stable transform that relocates paths aliases at emit time?