The moduleResolution setting in tsconfig.json determines how TypeScript finds imported modules. Choosing the right mode is critical:
| Mode | Use When | Extensions |
|---|---|---|
| bundler | Using Vite, webpack, esbuild, Turbopack | Optional (.js or none) |
| nodenext | Node.js libraries and apps (ESM or CJS) | Required (.js) |
| node16 | Same as nodenext (targeting Node 16+) | Required (.js) |
| node10 | Legacy - avoid for new projects | Optional |
// tsconfig.json for a Vite/bundler project
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "bundler",
"target": "ES2022",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"outDir": "./dist"
}
}
// tsconfig.json for a Node.js ESM project
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"target": "ES2022",
"strict": true,
"outDir": "./dist"
}
}With nodenext resolution, you must use .js extensions in imports - even when importing .ts files. This is because TypeScript emits .js files:
// src/utils.ts - your TypeScript source file
export function add(a: number, b: number): number {
return a + b;
}
// src/app.ts - importing with .js extension
import { add } from './utils.js'; // .js, not .ts!
// TypeScript knows utils.js refers to utils.ts at compile time
// At runtime, the emitted utils.js file exists
// This will NOT work with nodenext:
import { add } from './utils'; // Error!
import { add } from './utils.ts'; // Error!TypeScript 5.8+ Alternative:
The --rewriteRelativeImportExtensions flag lets you write import './utils.ts' and TypeScript will automatically rewrite it to ./utils.js in the output.
When publishing TypeScript packages as ESM, declaration files (.d.ts) need special handling:
// package.json - ESM package with TypeScript types
{
"name": "my-esm-library",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
},
"./utils": {
"types": "./dist/utils.d.ts",
"import": "./dist/utils.js"
}
},
"files": ["dist"]
}
// tsconfig.json for building the library
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"declaration": true,
"declarationMap": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"]
}Key Rule:
Always put "types" first in the exports conditions. TypeScript checks conditions in order and stops at the first match. If "import" comes before "types", TypeScript will try to use the .js file for type resolution.
// --erasableSyntaxOnly flag
// Ensures your TypeScript only uses syntax that can be
// "erased" (removed) to produce valid JavaScript
// Required for Node.js 24 built-in type stripping
// --rewriteRelativeImportExtensions
// Write .ts imports, get .js in output
import { utils } from './utils.ts';
// Emits: import { utils } from './utils.js';// import defer support (TC39 Stage 3)
import defer * as analytics from './analytics.js';
// TypeScript understands the defer semantics:
// - Type checking works normally
// - No execution until property access
// - Supports full IntelliSense
function trackEvent(name: string) {
analytics.track(name); // Evaluated here
}TypeScript 7 is a ground-up rewrite in Go, delivering 8-10x faster compilation. Key module changes:
moduleResolution: "bundler" in TypeScript 6.0+What This Means:
TypeScript 7 fully embraces modern module systems. If your project still uses AMD, UMD, or old-style module resolution, you will need to migrate before upgrading to TypeScript 7.
Multiple options for executing TypeScript without a manual compile step:
# Node.js 24+ built-in type stripping
node app.ts # Works for erasable syntax!
# tsx - TypeScript execute (any Node.js version)
npx tsx app.ts
npx tsx --watch app.ts # Watch mode
# ts-node with ESM support
node --loader ts-node/esm app.ts
# Deno - native TypeScript, no config needed
deno run app.ts
# Bun - native TypeScript, no config needed
bun run app.tsNode.js Type Stripping Limitations:
Node.js 24 only strips type annotations. Features that require transformation (enums, namespaces, decorators, parameter properties) need the --experimental-transform-types flag or a tool like tsx.
Missing .js extensions with nodenext
Use import './utils.js' not import './utils'. Or switch to moduleResolution: "bundler".
"types" condition after "import" in exports
Always put "types" first in package.json exports conditions.
Using module: "commonjs" with type: "module"
If package.json has "type": "module", use "module": "nodenext" or "module": "ESNext" in tsconfig.
esModuleInterop with nodenext
esModuleInterop is not needed with nodenext resolution - it's only for CJS interop in older modes.
When using moduleResolution 'node16' or 'nodenext', TypeScript requires .js extensions in imports even for .ts files. This is because TypeScript outputs .js files and the runtime needs to resolve the actual file. Use 'bundler' moduleResolution if your project uses a bundler, which allows extensionless imports.
Use 'nodenext' for Node.js libraries and applications. Use 'bundler' for projects that use Vite, webpack, or other bundlers. In TypeScript 6.0+, 'bundler' becomes the default. Avoid the legacy 'node10' setting for new projects.
TypeScript 7 (mid-2026) is rewritten in Go for 8-10x faster builds. It removes AMD, UMD, and SystemJS module output formats, and drops the legacy 'node10' module resolution. Only modern module formats are supported.
Yes! Node.js 24+ has built-in TypeScript type stripping that executes .ts files directly for erasable syntax. For full TypeScript features, use tools like tsx, ts-node, or Bun which handle TypeScript natively.