The Node.js ESM Resolution Algorithm has only two responsibilities:

Resolve the specifier in import to a final URL
Determine the module format corresponding to that URL

For example:

import react from "react";
import util from "./utils.js";
import config from "#config";

Node.js ultimately needs to obtain:

TEXT

react      -> file:///project/node_modules/react/index.js
./utils.js -> file:///project/src/utils.js
#config    -> file:///project/src/config/index.js

And:

TEXT

module
commonjs
json
wasm

And other module formats.

The entire ESM specification essentially describes:

TEXT

specifier
    ↓
resolved URL
    ↓
module format
    ↓
load
    ↓
execute

1. ESM_RESOLVE Overall Flow

The entry algorithm for Node.js ESM:

TEXT

ESM_RESOLVE(specifier, parentURL)

Can be simplified to:

TEXT

Determine specifier type

URL
path
#imports
bare package name

        ↓

Parse to get URL

        ↓

Check if file is valid

        ↓

Determine module format

        ↓

Return to Loader

The core goal of the entire algorithm:

TEXT

specifier
      ↓
unique URL

Rather than the constant guessing used in CommonJS.

2. Specifier Classification

Node.js divides specifiers into four categories.

1. URL Specifier

For example:

import x from "file:///app/src/a.js";

Or:

import x from "data:text/javascript,export default 1";

If it's already a valid URL:

TEXT

new URL(specifier)

Succeeds.

Then return directly.

2. Relative Specifier

For example:

import x from "./foo.js";
import y from "../bar.js";

Node.js resolves based on the current module's location.

Assuming:

TEXT

file:///app/src/main.js

Executing:

import "./utils.js";

Results in:

TEXT

file:///app/src/utils.js

Essentially:

new URL("./utils.js", parentURL)

3. Package Imports

For example:

import db from "#db";

Or:

import logger from "#utils/logger";

Starts with:

TEXT

Enters:

TEXT

PACKAGE_IMPORTS_RESOLVE()

Reads the current package:

JSON

{
  "imports": {
    "#db": "./src/db/index.js",
    "#utils/*": "./src/utils/*.js"
  }
}

For example:

import db from "#db";

Ultimately obtains:

TEXT

./src/db/index.js

4. Bare Specifier

For example:

import react from "react";

import lodash from "lodash";

import axios from "axios";

Neither:

TEXT

URL
path
#import

Is a bare package name.

Enters:

TEXT

PACKAGE_RESOLVE()

Starts searching node_modules.

3. PACKAGE_RESOLVE

This is the core logic for Node.js to find npm packages.

For example:

import react from "react";

Current file:

TEXT

/app/src/pages/home/index.js

Node.js keeps searching upward:

TEXT

/app/src/pages/home/node_modules/react
/app/src/pages/node_modules/react
/app/src/node_modules/react
/app/node_modules/react
/node_modules/react

Until found.

Equivalent to:

TEXT

while(currentDirectory){
   查找 node_modules/packageName
    找不到继续向上
}

4. Reading package.json

After finding the package:

TEXT

node_modules/react/package.json

Node.js starts reading the configuration.

Priority order:

TEXT

exports
    ↓
main
    ↓
direct path

5. exports Mechanism

Modern Node.js package resolution almost entirely relies on exports.

For example:

JSON

{
  "exports": {
    ".": "./dist/index.js",
    "./jsx-runtime": "./dist/jsx-runtime.js"
  }
}

Allows:

import React from "react";

Corresponds to:

TEXT

Obtains:

TEXT

./dist/index.js

Allows:

import jsx from "react/jsx-runtime";

Corresponds to:

TEXT

./jsx-runtime

Obtains:

TEXT

./dist/jsx-runtime.js

However:

import internal from "react/internal";

If:

JSON

"./internal"

Doesn't exist in exports, it errors with:

TEXT

Package Path Not Exported

6. Nature of exports

exports can be understood as:

TEXT

the public API a package exposes externally

For example:

JSON

{
  "exports": {
    ".": "./dist/index.js",
    "./api": "./dist/api.js"
  }
}

Allows:

import x from "my-lib";
import y from "my-lib/api";

Prohibits:

import z from "my-lib/dist/internal.js";

Even if the file actually exists.

7. Conditional Exports

exports doesn't have to be a string.

Can be an object.

For example:

JSON

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    }
  }
}

Node.js selects based on conditions.

ESM:

import x from "lib";

Matches:

JSON

"import"

Obtains:

TEXT

./dist/index.mjs

CommonJS:

require("lib");

Matches:

JSON

"require"

Obtains:

TEXT

./dist/index.cjs

8. PACKAGESELFRESOLVE

Assuming:

JSON

{
  "name": "my-lib",
  "exports": {
    ".": "./src/index.js",
    "./core": "./src/core.js"
  }
}

The current code is inside:

TEXT

my-lib

Then:

import core from "my-lib/core";

Won't search external node_modules.

Node.js will detect:

TEXT

current package name is my-lib

Directly uses the current package.json's exports.

This is:

TEXT

PACKAGE_SELF_RESOLVE

9. imports Mechanism

imports is very similar to exports.

The difference:

TEXT

exports is for others to use
imports is for yourself to use

For example:

JSON

{
  "imports": {
    "#db": "./src/db/index.js",
    "#utils/*": "./src/utils/*.js"
  }
}

Then:

import db from "#db";

Actual resolution:

TEXT

./src/db/index.js

Another example:

import stringUtil from "#utils/string.js";

Obtains:

TEXT

./src/utils/string.js

10. Pattern Match

imports and exports support wildcards.

For example:

JSON

{
  "exports": {
    "./features/*": "./src/features/*.js"
  }
}

Executing:

import user from "pkg/features/user";

Matches:

TEXT

Obtains:

TEXT

user

Finally:

TEXT

./src/features/user.js

11. PACKAGETARGETRESOLVE

This is where exports/imports actually perform mapping.

Supports four types.

String

JSON

{
  "exports": {
    ".": "./dist/index.js"
  }
}

Resolves directly.

Object

JSON

{
  "exports": {
    ".": {
      "node": "./node.js",
      "browser": "./browser.js",
      "default": "./index.js"
    }
  }
}

Selects based on conditions.

Array

JSON

{
  "exports": {
    ".": [
      "./native.js",
      "./fallback.js"
    ]
  }
}

If the first one fails.

Continues trying the next.

null

JSON

{
  "exports": {
    "./internal/*": null
  }
}

Explicitly prohibits export.

12. ESMFILEFORMAT

After URL location is complete.

Node.js needs to determine:

TEXT

what format should this file be loaded as?

.mjs

TEXT

module

.cjs

TEXT

commonjs

.json

TEXT

json

.wasm

TEXT

wasm

.node

TEXT

addon

Native extension module.

13. role of type Field

For:

TEXT

.js

Files.

Node.js searches for the nearest package.json.

For example:

JSON

{
  "type": "module"
}

Then:

app.js

Is interpreted as:

TEXT

ESM

If:

JSON

{
  "type": "commonjs"
}

Then:

app.js

Is interpreted as:

TEXT

CommonJS

Therefore:

TEXT

.mjs

Is always ESM.

TEXT

.cjs

Is always CommonJS.

TEXT

.js

Depends on type.

14. Why ESM Doesn't Support Directory Import

CommonJS:

require("./foo");

Node.js will try:

TEXT

foo.js
foo.json
foo.node
foo/index.js
foo/index.json

ESM:

import "./foo";

Doesn't guess.

If:

TEXT

foo

Is a directory.

Errors directly:

TEXT

Unsupported Directory Import

Correct写法:

import "./foo/index.js";

Or:

import "./foo.js";

15. LOOKUPPACKAGESCOPE

How does Node.js find the nearest package.json?

Algorithm:

TEXT

current directory
      ↓
parent directory
      ↓
continue upward
      ↓
until root directory

For example:

TEXT

/app/src/pages/home/index.js

Searches:

TEXT

/app/src/pages/home/package.json
/app/src/pages/package.json
/app/src/package.json
/app/package.json

Stops at the first one found.

16. Custom ESM Resolver

Node.js default resolution:

import x from "./a.js";
import y from "react";

If you want to support:

import x from "@/utils";

What to do?

Answer:

TEXT

Loader Hook

For example:

import { pathToFileURL } from "node:url";
import path from "node:path";

export async function resolve(
  specifier,
  context,
  nextResolve
) {
  if (specifier.startsWith("@/")) {
    return {
      url: pathToFileURL(
        path.resolve(
          process.cwd(),
          "src",
          specifier.slice(2)
        )
      ).href,
      shortCircuit: true
    };
  }

  return nextResolve(specifier, context);
}

Run:

BASH

node --loader ./loader.mjs app.js

After that:

import util from "@/utils.js";

Will automatically map to:

TEXT

src/utils.js

17. Complete Resolution Chain

Node.js ESM resolution can be summarized as:

TEXT

import specifier
        ↓
ESM_RESOLVE
        ↓
Determine type

URL
path
#imports
bare package name

        ↓

PACKAGE_RESOLVE

        ↓

exports
imports
main

        ↓

Get final URL

        ↓

ESM_FILE_FORMAT

        ↓

module
commonjs
json
wasm

        ↓

Loader

        ↓

Execute

Summary

The core idea of Node.js ESM is not "finding files."

But rather:

TEXT

specifier
      ↓
determine URL
      ↓
determine module format
      ↓
load and execute

The entire exports, imports, type, conditional exports, and loader mechanisms are fundamentally built around this goal.

The ESM resolution model is stricter, more static, and closer to the browser compared to CommonJS, making it more suitable for modern toolchains (Vite, Webpack, Rspack, Rollup, Turbopack) to analyze and optimize.

Understanding Node.js ESM Module Resolution Algorithm

Understanding Node.js ESM Module Resolution Algorithm

1. ESM_RESOLVE Overall Flow

2. Specifier Classification

1. URL Specifier

2. Relative Specifier

3. Package Imports

4. Bare Specifier

3. PACKAGE_RESOLVE

4. Reading package.json

5. exports Mechanism

6. Nature of exports

7. Conditional Exports

8. PACKAGESELFRESOLVE

9. imports Mechanism

10. Pattern Match

11. PACKAGETARGETRESOLVE

String

Object

Array

null

12. ESMFILEFORMAT

.mjs

.cjs

.json

.wasm

.node

13. role of type Field

14. Why ESM Doesn't Support Directory Import

15. LOOKUPPACKAGESCOPE

16. Custom ESM Resolver

17. Complete Resolution Chain

Summary