TypeScript 56 🔷 Module Resolution Strategies
In TypeScript 55, the module syntax was covered — import and export in their value, type-only, and side-effect forms. This chapter is about what happens when the compiler sees an import path: how it finds the file the path refers to. That is module resolution, and it is governed by the moduleResolution compiler option. The mode determines whether extensions are required, whether the exports field in package.json is honored, how node_modules is traversed, how path mappings work, and how conditional exports are selected. Choosing the wrong mode produces errors that are hard to diagnose: a package that resolves in the editor but fails at runtime, a relative import that works under one mode and errors under another, a package.json exports entry that is ignored. This chapter covers each mode, the algorithm each uses, the paths and baseUrl options, the exports and imports fields, and the rules that tie the resolution to the runtime.
Key point: The moduleResolution option determines the resolver. The legacy node (also called node10) mode resolves like Node’s CommonJS: extensionless imports, index.js, package.json main. The node16 and nodenext modes resolve like modern Node: file extensions are required in relative imports, and the exports field in package.json is honored. The bundler mode is designed for code that a bundler will process: extensionless imports are allowed, and the exports field is honored. The classic mode is the original TypeScript resolver and is rarely used. The mode must match the runtime: nodenext for Node, bundler for a bundled app, and node only for legacy compatibility.
What module resolution does
When the compiler sees import { User } from "./user", it must find the file that ./user refers to. The path is relative, and the file could be user.ts, user.tsx, user.d.ts, user/index.ts, or a JavaScript file with a matching declaration. The resolver tries the candidates in order and uses the first that exists.
The resolution inputs. The resolver uses the import path, the importing file’s location, the moduleResolution mode, the paths and baseUrl options, and the package.json files it finds along the way. The combination determines which file is selected.
Why the mode matters. The same import path can resolve to different files under different modes. ./user under node tries user.ts, user.tsx, user.d.ts, and user/index.ts. Under node16, the import must include the extension — ./user.js — because that is what the emitted JavaScript will use. The mode changes the rules, and the rules determine the result.
Why the resolution must match the runtime. The compiler resolves the import to a TypeScript file, but the runtime resolves the same import to a JavaScript file. If the two resolutions disagree — the compiler finds one file and the runtime finds another — the code fails at runtime even though it compiles. The mode is how the compiler is told which runtime to match.
Why the errors are confusing. A resolution error says “Cannot find module ‘./user’ or its corresponding type declarations.” The message does not say which mode is in use or which candidates were tried. The diagnosis requires knowing the mode and the algorithm, which is what this chapter provides.
Why the mode should be set explicitly. If moduleResolution is not set, TypeScript infers it from the module option. module: commonjs implies node, module: nodenext implies nodenext, and so on. The inference is usually correct, but setting the option explicitly makes the intent clear and prevents surprises when the module option changes.
Why the resolution is a compile-time concern. The emitted JavaScript has the same import path as the source, with the extension as the developer wrote it. The runtime resolves the path according to its own rules — Node’s rules for a Node application, the bundler’s rules for a bundled app. The compiler’s job is to resolve the path to a TypeScript file so it can check the types, and to emit the path in a form that the runtime will resolve to the same module. The mode is what aligns the two.
The classic mode
The classic mode is TypeScript’s original resolver. It is rarely used today and exists for historical compatibility.
{ "compilerOptions": { "moduleResolution": "classic" } }The algorithm walks up the directory tree from the importing file, looking for the module name as a file or a directory. For a relative import, it looks for the file in the current directory and then in the parent directories. It does not understand node_modules in the Node way, and it does not honor the exports field.
Why classic exists. It was the resolver for TypeScript’s early years, before Node’s module system became the dominant model. It is still used in a few legacy projects, but it is not the default for new code.
Why classic is not recommended. It does not match any runtime’s resolution. A project that uses classic compiles, but the emitted code does not resolve correctly under Node or under a bundler. The mode is a legacy artifact, and new projects should not use it.
When classic appears. A tsconfig.json that does not set moduleResolution and sets module: amd or module: system gets classic by inference. A project that has not been updated since the early TypeScript years may still have it. The fix is to set the mode explicitly to match the runtime.
The node mode (node10)
The node mode, also called node10, resolves like Node’s CommonJS. It is the traditional mode and remains common for libraries that target bundlers.
{ "compilerOptions": { "moduleResolution": "node" } }The algorithm looks for the module in node_modules, starting from the importing file’s directory and walking up. It tries the file with extensions .ts, .tsx, .d.ts, then .js, .jsx, then the directory’s index files, then the package.json‘s main field.
The candidate order for ./user.
./user.ts./user.tsx./user.d.ts./user/package.json(themainortypesfield)./user/index.ts./user/index.tsx./user/index.d.ts
The first that exists is used. The extensionless import works because the resolver tries the extensions.
Why node is still common. Many packages are published for bundlers, and the bundler’s resolver is closer to node than to node16. The node mode accepts extensionless imports, which is what most code uses, and it resolves the main field of package.json, which is the traditional entry point.
Why node is not correct for modern Node. Modern Node’s ESM requires file extensions in relative imports and honors the exports field. The node mode does neither. A project that uses node and runs on Node’s ESM resolves differently at runtime than at compile time, and the mismatch produces “module not found” errors at runtime.
Why the exports field is ignored. The exports field is the modern way for a package to declare its entry points. The node mode does not read it; it reads main and types instead. A package that relies on exports — with conditional exports for ESM and CommonJS — is resolved incorrectly under node.
Why node is sometimes called node10. The name node10 was introduced to distinguish it from node16 and nodenext. It refers to the behavior of Node 10, which was the Node version at the time the mode was current. The name is the same resolver as node, and both are accepted.
The node16 and nodenext modes
The node16 and nodenext modes resolve like modern Node’s ESM and CommonJS. They are the correct modes for a project that runs on Node.
{ "compilerOptions": { "moduleResolution": "nodenext" } }The algorithm honors the exports field in package.json, requires file extensions in relative imports, and distinguishes ESM from CommonJS by the file extension and the "type" field.
The extension requirement. A relative import must include the .js extension, because that is what the emitted JavaScript will use.
// user.ts
export interface User { id: string; }
// app.ts — under node16 or nodenext
import { User } from "./user.js"; // ✅ the .js extension is required
// import { User } from "./user"; // ❌ error: extension required
// import { User } from "./user.ts"; // ❌ error: .ts is not allowedThe .js extension in the source refers to the emitted .js file, not the source .ts file. The compiler resolves ./user.js to ./user.ts at compile time, and the runtime resolves ./user.js to the actual ./user.js at runtime. The two agree.
Why the extension is required. Node’s ESM requires the extension. The TypeScript source must use the same path the runtime will use. The rule is what makes the compile-time and runtime resolutions agree.
Why .ts is not allowed. The emitted file is .js, not .ts. An import with .ts would fail at runtime because no .ts file exists. The compiler rejects the import to prevent the runtime error.
The exports field. The node16 mode reads the exports field in a package’s package.json and uses it to resolve subpath imports.
// node_modules/some-package/package.json
{
"name": "some-package",
"exports": {
".": {
"import": "./esm/index.js",
"require": "./cjs/index.js"
},
"./utils": {
"import": "./esm/utils.js",
"require": "./cjs/utils.js"
}
}
}An import of some-package resolves to ./esm/index.js under ESM and ./cjs/index.js under CommonJS. An import of some-package/utils resolves to the corresponding file. The exports field is the package’s declared interface, and the mode honors it.
Why the exports field matters. A package that declares exports has a defined public interface. Subpaths not in the exports field are not importable, even if the files exist. This is the mechanism that prevents deep imports into a package’s internals. The node mode ignores this, so a deep import that works under node fails under node16.
Why node16 and nodenext are similar. The node16 mode targets Node 16’s resolution, and nodenext targets the latest Node. The behaviors are nearly identical; the difference is in the details of the exports field and the conditions. For most projects, nodenext is the choice.
Why the mode requires the module option to match. The moduleResolution: nodenext should be paired with module: nodenext. The two work together to emit the correct format and resolve the correct paths. A mismatch — module: esnext with moduleResolution: nodenext — produces inconsistent behavior.
The bundler mode
The bundler mode is designed for code that a bundler will process. It accepts extensionless imports and honors the exports field, matching the behavior of Vite, Webpack, and esbuild.
{ "compilerOptions": { "moduleResolution": "bundler" } }The mode allows extensionless relative imports, reads the exports field, and supports the imports field for the # prefix. It is the recommended mode for applications built with a bundler.
Why bundler is different from node16. The bundler resolves the extensionless import at build time, so the extension is not required in the source. The node16 mode requires the extension because the runtime does not do the resolution. The difference is in who resolves the path: the bundler at build time, or Node at runtime.
Why bundler is the modern default for applications. Most applications are built with a bundler, and the bundler’s resolution is the one that matters. The bundler mode matches the bundler’s rules, so the compile-time and build-time resolutions agree. The node16 mode would require extensions in every relative import, which is unnecessary for a bundled application.
The imports field. The bundler mode supports the imports field in package.json, which declares internal aliases with a # prefix.
{
"imports": {
"#utils/*": "./src/utils/*.ts"
}
}An import of #utils/format resolves to ./src/utils/format.ts. The imports field is the package’s internal alias mechanism, and it works without a bundler-specific configuration.
Why bundler does not support the paths field the same way. The paths option is a TypeScript-specific mapping, and the bundler does not read it. The paths must be duplicated in the bundler’s configuration (Vite’s resolve.alias, Webpack’s resolve.alias), or replaced by the imports field, which the bundler reads natively.
Why the mode is paired with module: esnext or module: preserve. The bundler mode emits ESM, and the module option should be esnext or preserve. The preserve option is newer and emits the imports as written without transformation, which matches the bundler’s expectations.
Why the mode is not for libraries. A library is consumed by other projects, which may use different resolvers. A library should use node16 or nodenext so that its declarations resolve correctly for every consumer. The bundler mode is for applications, not libraries.
Why the choice between
bundlerandnodenextis the runtime. If the code runs through a bundler — a browser app, a Vite app, an esbuild build — usebundler. If the code runs directly on Node — a CLI, a server, a library — usenodenext. The mode is the runtime, and the runtime is the decision.
The paths and baseUrl options
The paths option declares aliases for import paths, and the baseUrl option sets the base for non-relative imports. Together they are the mechanism for a project’s internal aliases.
{
"compilerOptions": {
"baseUrl": "./src",
"paths": {
"@app/*": ["app/*"],
"@utils/*": ["utils/*"],
"@models/*": ["models/*"]
}
}
}An import of @utils/format resolves to src/utils/format under the baseUrl and the paths mapping. The @ prefix is a convention that distinguishes internal aliases from package imports.
Why paths is useful. A deep relative import like ../../../../utils/format is hard to read and fragile — moving the file breaks the import. An alias like @utils/format is stable and readable. The paths option is the way to declare the aliases.
Why baseUrl is sometimes omitted in modern TypeScript. In TypeScript 4.1 and later, paths works without baseUrl, with the paths resolved relative to the tsconfig.json. The baseUrl is still useful when the aliases should be relative to a specific directory.
Why paths must be duplicated for the runtime. The paths option is TypeScript-specific. The runtime — Node or the bundler — does not read it. The aliases must be declared in the runtime’s configuration: Vite’s resolve.alias, Webpack’s resolve.alias, Jest’s moduleNameMapper, or the imports field in package.json.
// vite.config.ts
import { defineConfig } from 'vite';
import path from 'node:path';
export default defineConfig({
resolve: {
alias: {
'@app': path.resolve(__dirname, 'src/app'),
'@utils': path.resolve(__dirname, 'src/utils'),
'@models': path.resolve(__dirname, 'src/models'),
},
},
});The paths in tsconfig.json and the alias in the bundler’s configuration must agree. If they do not, the compiler resolves one path and the bundler resolves another, and the build fails or the runtime errors.
Why the imports field is preferred over paths for new projects. The imports field in package.json is read by both TypeScript and the bundler, so the alias is declared once. The paths option is a TypeScript-only mechanism that requires duplication. For a project that uses a bundler, the imports field is the more maintainable choice.
Why the paths mapping must have the wildcard. The * in @utils/* and utils/* is what makes the mapping work for multiple imports. A mapping without the wildcard is an exact match, which is rarely wanted. The wildcard is the mechanism for a prefix mapping.
The exports and imports fields
The exports and imports fields in package.json are the modern way to declare a package’s interface. They are honored by the node16, nodenext, and bundler modes, and ignored by the node mode.
The exports field. Declares the package’s public entry points.
{
"name": "my-package",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
},
"./utils": {
"types": "./dist/utils.d.ts",
"import": "./dist/utils.mjs",
"require": "./dist/utils.cjs"
}
}
}The . entry is the package’s main entry point, and the ./utils entry is a subpath. Each entry has conditions: types for the TypeScript declaration, import for ESM, require for CommonJS. The resolver picks the condition that matches the mode and the consumer.
Why the conditions matter. A package can provide different files for ESM and CommonJS, and the resolver picks the one that matches the consumer. The types condition provides the declaration file, which is what TypeScript uses. The import and require conditions provide the runtime files for each module system.
Why the types condition must come first. The conditions are checked in order, and the first match wins. The types condition must be first so that TypeScript picks it. If import comes first, TypeScript may resolve to the .mjs file and fail to find the declarations.
The imports field. Declares internal aliases with a # prefix.
{
"imports": {
"#internal/*": "./src/internal/*.ts",
"#config": "./src/config.ts"
}
}An import of #internal/helpers resolves to ./src/internal/helpers.ts. The # prefix distinguishes the internal aliases from package imports, and it is reserved for this purpose.
Why the imports field is for internal use. The imports field declares aliases that are used within the package, not by its consumers. The exports field declares what consumers can import. The two are separate, and the distinction is what makes the package’s interface explicit.
Why the fields are read only in the modern modes. The node mode reads main and types, not exports. A package that uses exports is resolved incorrectly under node. The modes that honor the fields are node16, nodenext, and bundler, which are the modes for modern code.
Why the
exportsfield can break existing code. A package that adds anexportsfield restricts its public interface to the declared entry points. A deep import likesome-package/internal/helperthat worked before the field was added fails afterward, because the subpath is not declared. The field is the package’s way of enforcing its interface, and the restriction is intentional. The fix for the consumer is to use the declared entry points.
Complete Example Session
// ============================================
// PART 1: RELATIVE IMPORT UNDER node16
// ============================================
// user.ts
export interface User { id: string; name: string; }
// app.ts
import type { User } from "./user.js"; // ✅ the .js extension
// import type { User } from "./user"; // ❌ extension required
// import type { User } from "./user.ts"; // ❌ .ts not allowed
// ============================================
// PART 2: RELATIVE IMPORT UNDER bundler
// ============================================
// app.ts
import type { User } from "./user"; // ✅ extensionless is fine
// ============================================
// PART 3: PACKAGE IMPORT
// ============================================
import { z } from "zod";
// Resolved through node_modules/zod
// The exports field declares the entry points
// ============================================
// PART 4: THE exports FIELD
// ============================================
// node_modules/some-package/package.json
// {
// "name": "some-package",
// "exports": {
// ".": {
// "types": "./dist/index.d.ts",
// "import": "./dist/index.mjs",
// "require": "./dist/index.cjs"
// },
// "./utils": {
// "types": "./dist/utils.d.ts",
// "import": "./dist/utils.mjs",
// "require": "./dist/utils.cjs"
// }
// }
// }
import { main } from "some-package"; // ✅ the "." entry
import { helper } from "some-package/utils"; // ✅ the "./utils" entry
// import { internal } from "some-package/internal"; // ❌ not declared
// ============================================
// PART 5: THE imports FIELD
// ============================================
// package.json
// {
// "imports": {
// "#utils/*": "./src/utils/*.ts",
// "#config": "./src/config.ts"
// }
// }
import { format } from "#utils/format"; // ✅
import { config } from "#config"; // ✅
// ============================================
// PART 6: THE paths OPTION
// ============================================
// tsconfig.json
// {
// "compilerOptions": {
// "baseUrl": "./src",
// "paths": {
// "@app/*": ["app/*"],
// "@utils/*": ["utils/*"]
// }
// }
// }
import { format } from "@utils/format"; // ✅ resolved to src/utils/format
// The bundler must declare the same alias.
// ============================================
// PART 7: THE vite.config.ts ALIAS
// ============================================
// vite.config.ts
// import { defineConfig } from 'vite';
// import path from 'node:path';
//
// export default defineConfig({
// resolve: {
// alias: {
// '@app': path.resolve(__dirname, 'src/app'),
// '@utils': path.resolve(__dirname, 'src/utils'),
// },
// },
// });
// ============================================
// PART 8: TSCONFIG FOR A NODE LIBRARY
// ============================================
// {
// "compilerOptions": {
// "target": "es2022",
// "module": "nodenext",
// "moduleResolution": "nodenext",
// "verbatimModuleSyntax": true,
// "declaration": true,
// "outDir": "./dist",
// "strict": true
// }
// }
// ============================================
// PART 9: TSCONFIG FOR A BUNDLED APP
// ============================================
// {
// "compilerOptions": {
// "target": "es2022",
// "module": "esnext",
// "moduleResolution": "bundler",
// "verbatimModuleSyntax": true,
// "isolatedModules": true,
// "paths": {
// "@app/*": ["./src/app/*"]
// },
// "strict": true
// }
// }
// ============================================
// PART 10: WHAT NOT TO DO
// ============================================
// Don't use `node` for a modern Node project
// The exports field is ignored.
// Don't use `bundler` for a library
// The declarations do not resolve for consumers.
// Don't forget the .js extension under node16
// The runtime cannot resolve the path.
// Don't write .ts in an import
// The emitted file is .js.
// Don't declare a path alias in tsconfig only
// The bundler must declare the same alias.
// Don't mix moduleResolution and module
// The two must agree.
// Don't rely on deep imports into a package
// The exports field may forbid them.The ten parts cover the extension rules, the exports and imports fields, the paths option, the bundler alias, the two tsconfig.json configurations, and the anti-patterns.
Quick Reference
The Modes
| Mode | Extensions | exports | For |
|---|---|---|---|
classic | Optional | No | Legacy TypeScript |
node / node10 | Optional | No | Legacy bundlers |
node16 | Required | Yes | Node 16 |
nodenext | Required | Yes | Modern Node |
bundler | Optional | Yes | Bundled apps |
Extension Rules
| Mode | ./user | ./user.js | ./user.ts |
|---|---|---|---|
node | ✅ | ✅ | ❌ |
node16 / nodenext | ❌ | ✅ | ❌ |
bundler | ✅ | ✅ | ❌ |
The exports Field Conditions
| Condition | For |
|---|---|
types | TypeScript declarations |
import | ESM |
require | CommonJS |
default | Fallback |
The paths and baseUrl
| Option | Purpose |
|---|---|
baseUrl | Base directory for non-relative imports |
paths | Alias mappings |
paths without baseUrl | Resolved relative to tsconfig.json |
Bundler alias | The runtime equivalent |
Configuration Pairs
| Project | module | moduleResolution |
|---|---|---|
| Node library | nodenext | nodenext |
| Bundled app | esnext | bundler |
| Legacy Node | commonjs | node |
| Bundled library | esnext | bundler (with declaration) |
Common Errors
| Error | Cause |
|---|---|
| “Cannot find module ‘./user'” | Extension missing under node16 |
| “Cannot find module ‘pkg/sub'” | Subpath not in exports |
| “The current file is a CommonJS module” | ESM import in a CJS file |
| “Cannot find name ‘require'” | CJS code in an ESM file |
Best Practices
✅ Do This:
// Use .js extensions under node16 and nodenext
import type { User } from "./user.js"; // ✅
// Use extensionless under bundler
import type { User } from "./user"; // ✅
// Declare path aliases in both tsconfig and the bundler
// tsconfig: paths; vite: resolve.alias // ✅
// Use the imports field for internal aliases
// package.json: "imports": { "#utils/*": "./src/utils/*.ts" } // ✅
// Use the exports field for a library's public interface
// "exports": { ".": { "types": ..., "import": ..., "require": ... } } // ✅
// Match module and moduleResolution
{ "module": "nodenext", "moduleResolution": "nodenext" } // ✅
// Use bundler for applications
{ "moduleResolution": "bundler" } // ✅❌ Don’t Do This:
// Don't write .ts in an import
import { User } from "./user.ts"; // ❌ // ⚠️
// Don't omit the extension under node16
import { User } from "./user"; // ❌ // ⚠️
// Don't use node for a modern Node project
{ "moduleResolution": "node" } // ignores exports // ⚠️
// Don't use bundler for a library
{ "moduleResolution": "bundler" } // declarations break // ⚠️
// Don't declare aliases in tsconfig only
// The bundler must know the aliases too // ⚠️
// Don't rely on deep imports into a package
// The exports field may forbid them // ⚠️
// Don't mix module and moduleResolution
{ "module": "esnext", "moduleResolution": "nodenext" } // ⚠️Common Pitfalls
| Pitfall | Problem | Solution |
|---|---|---|
Missing .js under node16 | Cannot find module | Add the extension |
.ts extension in import | Compile error | Use .js |
node ignores exports | Wrong resolution | Use node16/bundler |
bundler for a library | Declarations break | Use nodenext |
| Aliases in tsconfig only | Runtime cannot resolve | Duplicate in bundler |
types condition not first | TypeScript picks import | Reorder the conditions |
| Deep import blocked | Subpath not declared | Use the entry points |
Mismatched module and mode | Inconsistent behavior | Pair them correctly |
Real-World Examples
1. node16 relative import
import type { User } from "./user.js";2. bundler relative import
import type { User } from "./user";3. Package import
import { z } from "zod";4. Subpath import
import { helper } from "some-package/utils";5. Internal alias with #
import { format } from "#utils/format";6. Path alias
import { format } from "@utils/format";7. Bundler alias
// vite.config.ts: resolve.alias8. Node library tsconfig
{ "module": "nodenext", "moduleResolution": "nodenext" }9. Bundled app tsconfig
{ "module": "esnext", "moduleResolution": "bundler" }10. The exports field
{ ".": { "types": "./dist/index.d.ts", "import": "./dist/index.mjs" } }Visual: The Modes
┌──────────────────────────────────────────────────────────┐
│ classic │
│ Original TypeScript. Rarely used. │
│ │
├──────────────────────────────────────────────────────────┤
│ node (node10) │
│ Node CommonJS. Extensionless. main field. │
│ Ignores exports. For legacy. │
│ │
├──────────────────────────────────────────────────────────┤
│ node16 / nodenext │
│ Modern Node. Extensions required. exports honored. │
│ For Node applications and libraries. │
│ │
├──────────────────────────────────────────────────────────┤
│ bundler │
│ Extensionless. exports honored. imports honored. │
│ For applications built with a bundler. │
│ │
└──────────────────────────────────────────────────────────┘Visual: Extension Rules
┌──────────────────────────────────────────────────────────┐
│ node16 / nodenext │
│ │
│ import { x } from "./mod.js" ✅ │
│ import { x } from "./mod" ❌ │
│ import { x } from "./mod.ts" ❌ │
│ │
│ The source uses .js because the emitted file is .js. │
│ │
├──────────────────────────────────────────────────────────┤
│ bundler │
│ │
│ import { x } from "./mod" ✅ │
│ import { x } from "./mod.js" ✅ │
│ import { x } from "./mod.ts" ❌ │
│ │
│ The bundler resolves the extension at build time. │
│ │
├──────────────────────────────────────────────────────────┤
│ node (node10) │
│ │
│ import { x } from "./mod" ✅ │
│ import { x } from "./mod.js" ✅ │
│ │
│ The resolver tries the extensions. │
│ │
└──────────────────────────────────────────────────────────┘Visual: The exports Field
┌──────────────────────────────────────────────────────────┐
│ node_modules/some-package/package.json │
│ │
│ { │
│ "exports": { │
│ ".": { │
│ "types": "./dist/index.d.ts", │
│ "import": "./dist/index.mjs", │
│ "require": "./dist/index.cjs" │
│ }, │
│ "./utils": { │
│ "types": "./dist/utils.d.ts", │
│ "import": "./dist/utils.mjs", │
│ "require": "./dist/utils.cjs" │
│ } │
│ } │
│ } │
│ │
│ import from "some-package" → the "." entry │
│ import from "some-package/utils" → the "./utils" entry │
│ import from "some-package/internal" → ❌ not declared │
│ │
│ The exports field is the package's interface. │
│ │
└──────────────────────────────────────────────────────────┘Visual: The imports Field
┌──────────────────────────────────────────────────────────┐
│ package.json │
│ │
│ { │
│ "imports": { │
│ "#utils/*": "./src/utils/*.ts", │
│ "#config": "./src/config.ts" │
│ } │
│ } │
│ │
│ import { format } from "#utils/format" │
│ → ./src/utils/format.ts │
│ │
│ import { config } from "#config" │
│ → ./src/config.ts │
│ │
│ The # prefix is reserved for internal aliases. │
│ Read by TypeScript and the bundler. │
│ │
└──────────────────────────────────────────────────────────┘Visual: The paths Option
┌──────────────────────────────────────────────────────────┐
│ tsconfig.json │
│ │
│ { │
│ "compilerOptions": { │
│ "baseUrl": "./src", │
│ "paths": { │
│ "@utils/*": ["utils/*"] │
│ } │
│ } │
│ } ││ │
│ import { format } from "@utils/format" │
│ → src/utils/format.ts │
│ │
│ The bundler must declare the same alias: │
│ resolve.alias { "@utils": "src/utils" } │
│ │
│ Without the duplication, the bundler fails. │
│ │
└──────────────────────────────────────────────────────────┘Visual: Choosing the Mode
┌──────────────────────────────────────────────────────────┐
│ Where does the code run? │
│ │ │
│ ├── Node directly │
│ │ └── node16 / nodenext │
│ │ │
│ ├── A bundler (Vite, Webpack, esbuild) │
│ │ └── bundler │
│ │ │
│ ├── A library consumed by others │
│ │ └── node16 / nodenext │
│ │ │
│ └── Legacy Node or a bundler │
│ └── node (node10) │
│ │
│ The mode must match the runtime. │
│ │
└──────────────────────────────────────────────────────────┘Summary
| Mode | Extensions | exports | For |
|---|---|---|---|
classic | Optional | No | Legacy |
node | Optional | No | Legacy Node/bundlers |
node16 | Required | Yes | Node 16 |
nodenext | Required | Yes | Modern Node |
bundler | Optional | Yes | Bundled apps |
| Option | Purpose |
|---|---|
baseUrl | Base for non-relative imports |
paths | Alias mappings |
exports | Package public interface |
imports | Internal aliases (#) |
resolve.alias | Bundler alias |
Key takeaways:
- Module resolution is the algorithm that finds the file an import path refers to — the
moduleResolutionmode selects the algorithm node(node10) resolves like Node’s CommonJS — extensionless imports,mainfield,exportsignored — and is for legacy compatibilitynode16andnodenextresolve like modern Node — file extensions are required in relative imports, and theexportsfield is honoredbundlerresolves like a bundler — extensionless imports are allowed, and theexportsandimportsfields are honored- The mode must match the runtime —
nodenextfor Node,bundlerfor a bundled app,nodeonly for legacy - The
.jsextension is required undernode16andnodenext— the source uses the same path the emitted JavaScript will use - The
exportsfield declares a package’s public interface — the conditionstypes,import, andrequireare checked in order, andtypesmust come first - The
importsfield declares internal aliases with a#prefix, and it is read by both TypeScript and the bundler - The
pathsoption is TypeScript-only — the aliases must be duplicated in the bundler’s configuration, or replaced by theimportsfield - The mode and the
moduleoption must agree —nodenextwithnodenext,esnextwithbundler— and a mismatch produces inconsistent behavior
Remember: Module resolution is the bridge between the import path in the source and the file the compiler and the runtime use. The mode selects the algorithm, and the algorithm must match the runtime. Use nodenext for Node, bundler for a bundled app, and node only for legacy. Require extensions under node16, honor the exports field in modern modes, and duplicate the path aliases for the bundler. The rules are what make the compile-time and runtime resolutions agree.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!