Model modern Node.js resolution
A project runs directly on current Node.js and may use both ESM imports and CommonJS require.
TypeScript · Const
moduleResolution
moduleResolution chooses how TypeScript maps import, export, and require specifiers to files. Configure it to match the target runtime or bundler, such as nodenext for modern Node.js or bundler for bundler-managed projects.
How it works
moduleResolution selects the algorithm TypeScript uses to turn module specifiers from imports, exports, or require calls into files. Choose a mode that matches the runtime or bundler: node16/nodenext for modern Node.js, bundler for bundlers, and node10 only for older CommonJS environments.
Syntax
"moduleResolution": "node16" | "nodenext" | "node10" | "bundler" | "classic"Parameters
| Name | Type | Description |
|---|---|---|
moduleResolution | `node16` | `nodenext` | `node10` | `bundler` | `classic` | Resolution strategy used to locate files for module specifiers. Current documented choices include node16, nodenext, node10, bundler, and classic. |
Returns
No runtime return value; this compiler option changes how TypeScript resolves modules.
Key points
- The option maps strings in import, export, and require statements to files on disk.
- Treat the runtime or bundler as the source of truth when selecting a resolution strategy.
- Modern Node.js projects generally use node16 or nodenext.
- Select bundler when a bundler, rather than Node.js directly, resolves application modules.
- Bundler, node16, and nodenext understand package entry-point and internal-import maps.
- When runtime-style lookup points at JavaScript, TypeScript substitutes a corresponding TypeScript source or declaration file first.
Common mistakes
- Node16 and NodeNext must be paired with corresponding module settings so resolution reflects whether emitted code uses import or require.
- Bundler mode accepts extensionless relative imports, so code that works there may not satisfy Node.js's stricter import rules.
- Avoid node10 for new projects; it models older Node.js CommonJS behavior.
- Do not choose the classic strategy for current projects.
Example: Use NodeNext module resolution
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"target": "es2022"
}
}Use Node's modern resolution rules for a Node.js project so TypeScript models the runtime's import and require behavior.
When to use it
Match bundler behavior
A web application is resolved and emitted by a bundler.
Support legacy Node.js
A legacy application targets an older Node.js CommonJS environment.
Interview questions
QWhat does moduleResolution control?
It determines how TypeScript resolves module specifiers to files. The setting should match the module-resolution behavior of the target runtime or bundler.
Follow-up: How would you choose it for a bundled web application versus a Node.js application? Use bundler for the former and nodenext or node16 for the latter, paired with the corresponding module setting.
QWhich strategy is appropriate for modern Node.js?
Use node16 or nodenext for modern Node.js. These modes account for Node.js supporting both ECMAScript imports and CommonJS require, which use different resolution algorithms.
Follow-up: Why must the module option also matter? The emitted form determines whether Node.js applies import or require resolution, so the paired settings let TypeScript select the appropriate algorithm.
QHow does bundler differ from Node.js resolution?
Use bundler when a bundler performs resolution. It supports package imports and exports while allowing extensionless relative imports, unlike Node.js resolution modes.
Follow-up: What compatibility issue can this create? Code accepted by bundler may fail when executed directly by Node.js because Node.js can require extensions on relative imports.
Related
modulebaseUrlpathsresolveJsonModuleesModuleInterop