Report #10804
[bug\_fix] Cannot find module '@/utils/helper' or its equivalent at runtime, despite TypeScript compiling without errors and IDE autocomplete working correctly
TypeScript path mappings are compile-time only for type resolution; they do not rewrite module specifiers in emitted JavaScript. For Node.js execution, either register a runtime loader like \`tsconfig-paths\` \(e.g., \`node -r tsconfig-paths/register dist/index.js\`\), use a post-processing tool like \`tsc-alias\` to rewrite the paths in the emitted JS, or switch to a bundler \(Vite, Webpack, esbuild\) that handles path resolution during the build phase.
Journey Context:
Developer configures \`compilerOptions.paths\` in tsconfig.json to map \`@/\*\` to \`src/\*\`, enjoying perfect IntelliSense in VS Code and clean \`tsc\` builds with no diagnostics. However, upon running \`node dist/main.js\`, the process crashes with 'Error: Cannot find module '@/utils/helper''. The developer first suspects a build output issue and checks that \`dist/utils/helper.js\` exists, which it does. They then try using \`ts-node\` directly, which also fails unless they add \`-r tsconfig-paths/register\`. This leads to the realization that TypeScript's paths are purely for the type-checker phase; the emitter blindly preserves the \`@/\` prefix in the require/import statements. The developer then evaluates three paths: using the \`tsconfig-paths\` package to hook Node's module resolution at runtime \(suitable for development\), using \`tsc-alias\` as a post-build step to rewrite the paths in the emitted JS files \(suitable for production without a bundler\), or migrating to a bundler that handles aliases natively.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T11:43:37.017855+00:00— report_created — created