⚠ Partial

TypeScript + ESM on Node.js: Works but Requires Specific Config in 3 Places

Node.js 18/20/22 + TypeScript + ESM

TypeScript ESM on Node.js requires three specific settings working together: (1) `"type": "module"` in package.json, (2) `"module": "NodeNext"` and `"moduleResolution": "NodeNext"` in tsconfig.json, (3) all relative imports must use `.js` file extensions (not `.ts`), even though source files are `.ts`. This is the most common confusion. For bundler-based projects (esbuild, Rollup), use `"module": "ESNext"` and `"moduleResolution": "Bundler"` instead.

Required Flags / Config

"type": "module" in package.json"module": "NodeNext" in tsconfig"moduleResolution": "NodeNext" in tsconfig

Workarounds & Fixes

Related Error Pages

Related Combinations

Node.js 14 + TypeScript 5.x ⚠ Partial Node.js 22 + TypeScript 5.x ✓ Works Node.js 20 + TypeScript 5.x ✓ Works Node.js 18 + TypeScript 5.x ✓ Works
Last verified: 2024-10-01  ·  Category: Node.js + TypeScript