tsconfig paths aliases fail at runtime after emit despite passing type-check

The Core Conflict: Compile-Time vs. Runtime

TypeScript's baseUrl and paths settings are strictly for the compiler's type-checking and module-resolution phases. The TypeScript compiler (tsc) does not rewrite these aliases into relative paths during the emit process. Consequently, if you import @app/utils, the emitted JavaScript file will still contain require('@app/utils') or import ... from '@app/utils', which Node.js cannot resolve natively.

Node.js ESM and Module Resolution

For Node.js ESM, no combination of module and moduleResolution (including node16 or nodenext) will cause tsc to transform aliases into relative paths. These settings change how TypeScript finds the files for type-checking, but they do not change the output string of the import specifier.

To achieve alias-like behavior in native Node.js ESM without a bundler, you must use the imports field in package.json. This is a native Node.js feature that mirrors tsconfig paths:

// package.json
{
  "imports": {
    "#app/*": "./dist/app/*"
  }
}

Note: Native Node.js imports must start with a hash (#) to distinguish them from scoped packages.

Synchronizing Bundlers with tsconfig

To ensure a production bundler mirrors tsconfig paths without maintaining a duplicate list, use a plugin that reads the tsconfig.json file directly during the build process:

• Vite: Use vite-tsconfig-paths.
• Webpack: Use tsconfig-paths-webpack-plugin.
• esbuild: Use esbuild-plugin-tsconfig-paths.

These tools intercept the resolution process and apply the tsconfig mappings at the bundling stage, eliminating configuration drift.

Emit-Time Transforms

There is no stable, built-in tsc option to relocate paths. For projects that cannot use a bundler or package.json imports, the industry standard is to use a post-emit transform tool such as tsc-alias. This tool scans the emitted JavaScript files and replaces the aliases with actual relative paths based on the tsconfig mapping.

Verification Steps

To confirm where the resolution is failing, perform these checks:

1. Inspect Emit: Run tsc and open a generated .js file. If the alias (e.g., @app/...) is still present, the compiler is behaving as expected (not transforming).
2. Test Runtime Shim: Run your app with node -r tsconfig-paths/register dist/index.js. If it works now, the issue is strictly the lack of runtime path resolution.

Diagnostic Detail Needed: Are you targeting a native Node.js runtime (no bundler) or using a build tool like Vite/Webpack?