Skip to content

Instantly share code, notes, and snippets.

@sapphi-red

sapphi-red/docs.md

Created May 1, 2025 08:33
Show Gist options
  • Save sapphi-red/2dc80aa0bef70864e2ffd5d2e3560728 to your computer and use it in GitHub Desktop.
Save sapphi-red/2dc80aa0bef70864e2ffd5d2e3560728 to your computer and use it in GitHub Desktop.
Download ZIP
An archive of a document I wrote when I tried to rewrite the resolver of Vite
Raw
docs.md

resolver

Node.js has different resolve algorithm for require (hereinafter, called "CJS resolver") and import (hereinafter, called "ESM resolver").

Spec of CJS resolver: https://nodejs.org/api/modules.html#all-together Spec of ESM resolver: https://nodejs.org/api/esm.html#resolver-algorithm-specification

Vite needs to support both of them.

Notes

specifier

Specifier is a string pass to import in ESM or require in CJS.

import 'foo'
import('foo')
require('foo')

For example, foo is a specifier in this case.

CJS resolver treats specifier as a simple file path. ESM resolver treats specifier as a URL unless it's a bare specifier.

So there's a difference between them handling special characters in URL.

module field

module field points to a ESM file. But because Node.js doesn't use that field, there are many files that won't work with ESM resolver in wild. So it needs to use CJS resolver.

Principle

Support all feature of ESM resolver and fallback to CJS resolver where it is possible.

Basic Algorithm

[ESM] means that step is related to ESM resolver. [CJS] means that step is related to CJS resolver.

condition: conditions to use for exports/imports

is_windows: whether it is running on Windows

RESOLVE(id, importer): (id, importer is both path)

  1. [ESM/CJS] Let resolved be undefined.
  2. [ESM/CJS] If id begins with "./" or "/" or "../" or (is_windows and matches /^\w:/)
    1. PATH_RESOLVE(id, importer)
  3. [ESM/CJS] Otherwise, if id begins with "#", then
    1. Set resolved to the result of PACKAGE_IMPORTS_RESOLVE(id, importer, condition).
    2. RESOLVE_ABSOLUTE(resolved)
  4. [ESM/CJS] Otherwise, if id matches /^\w+:/, then
    1. Note: CJS doesn't support URL protocols.
    2. [ESM] If id begins with "file:" or "data:" or "http:" or "https:" or "node:", then
      1. [ESM] RESOLVE_ABSOLUTE(id)
    3. [ESM/CJS] Fallback to other rollup/vite plugins. STOP
  5. [ESM/CJS] Otherwise,
    1. Note: id is now a bare specifier.
    2. Set resolved to the result of PACKAGE_RESOLVE(id, importer).
    3. If resolved is undefined, fallback to other rollup/vite plugins. STOP
    4. RESOLVE_ABSOLUTE(resolved)

RESOLVE_ABSOLUTE(id):

  1. [ESM] If id begins with "node:", then
    1. resolve that. STOP
  2. [ESM] If id begins with "file:", then
    1. If fileURLToPath(id) exists, resolve that. STOP
    2. Throw "not found"
  3. [ESM] If id begins with "data:" or "http:" or "https:", then
    1. resolve that. STOP
  4. [ESM/CJS] If id exists, resolve that. STOP
  5. [ESM/CJS] Throw "not found"

PATH_RESOLVE(id, importer)

  1. [ESM/CJS] Let absolute be path.resolve(importer, id).
  2. [ESM/CJS] LOAD_AS_FILE(absolute)
  3. [CJS] LOAD_AS_DIRECTORY(absolute)
  4. [ESM/CJS] Throw "not found"

LOAD_AS_FILE(id)

Same with LOAD_AS_FILE of CJS resolver

LOAD_INDEX(id)

Same with LOAD_INDEX of CJS resolver

LOAD_AS_DIRECTORY(id)

Same with LOAD_AS_DIRECTORY of CJS resolver

PACKAGE_RESOLVE(id, importer)

Similar with PACKAGE_RESOLVE of ESM resolver.

  1. [ESM/CJS] Let packageName be undefined.
  2. [ESM/CJS] If id is an empty string, then
    1. Fallback to other plugins. STOP
  3. [ESM/CJS] If id is a Node.js builtin module name, then
    1. resolve that. STOP
  4. [ESM/CJS] If id does not start with "@", then
    1. Set packageName to the substring of id until the first "/" separator or the end of the string.
  5. [ESM/CJS] Otherwise,
    1. If id does not contain a "/" separator, then
      1. Fallback to other plugins. STOP
    2. Set packageName to the substring of id until the second "/" separator or the end of the string.
  6. [ESM/CJS] Let packageSubpath be "." concatenated with the substring of id from the position at the length of packageName.
  7. [ESM/CJS] Let selfPath be the result of PACKAGE_SELF_RESOLVE(packageName, packageSubpath, pathToFileURL(importer)).
  8. [ESM/CJS] If selfPath is not undefined, return selfPath
  9. [ESM/CJS] Let resolved be result of LOAD_NODE_MODULES(packageName, packageSubpath, importer).
  10. [ESM/CJS] If resolved is not undefined, return resolved
  11. [ESM/CJS] Fallback to other plugins. STOP

PACKAGE_SELF_RESOLVE(packageName, packageSubpath, importer)

Same with PACKAGE_SELF_RESOLVE of ESM resolver. Note this corresponds to LOAD_PACKAGE_SELF of CJS resolver.

LOAD_NODE_MODULES(packageName, packageSubpath, importer)

Similar with LOAD_NODE_MODULES of CJS resolver.

  1. [ESM/CJS] Let dirs to be result of NODE_MODULES_PATHS(path.dir(importer)).
  2. [ESM/CJS] For each dir in dirs,
    1. LOAD_PACKAGE_EXPORTS(packageName, packageSubpath, dir)
    2. If packageSubpath is not ".", then
      1. LOAD_AS_FILE(dir + packageName + packageSubpath)
    3. LOAD_AS_DIRECTORY(dir + packageName + packageSubpath)

NODE_MODULES_PATHS(dir)

Similar with NODE_MODULES_PATHS of CJS resolver.

  1. [ESM/CJS] let parts = path split(dir)
  2. [ESM/CJS] let i = count of parts - 1
  3. [ESM/CJS] let dirs = []
  4. [ESM/CJS] while i >= 0,
    1. if parts[i] = "node_modules" continue
    2. dir = path join(parts[0 .. i] + "node_modules")
    3. dirs = dir + dirs
    4. i = i - 1
  5. [ESM/CJS] return dirs

LOAD_PACKAGE_EXPORTS(packageName, packageSubpath, dir)

Similar with LOAD_PACKAGE_EXPORTS of CJS resolver.

  1. Let packageDir to be dir + packageName
  2. Let pjson be the result of READ_PACKAGE_JSON(packageDir).
  3. If pjson is not null and pjson.exports is not null or undefined, then
    1. Return the result of PACKAGE_EXPORTS_RESOLVE(packageDir, packageSubpath, pjson.exports, conditions).

PACKAGE_IMPORTS_RESOLVE(id, importer, condition)

Same with PACKAGE_IMPORTS_RESOLVE of ESM resolver except the param takes path instead of URL.

PACKAGE_EXPORTS_RESOLVE(id, importer, condition)

Same with PACKAGE_EXPORTS_RESOLVE of ESM resolver except the param takes path instead of URL.

READ_PACKAGE_JSON(packageDir)

Same with PACKAGE_SELF_RESOLVE of ESM resolver except the param takes path instead of URL.

Caveats

extension

CJS resolver supports omitting extension and omitting /index part. ESM resolver doesn't support that, but Vite core support this in some cases.

virtual packages: invalid package name

CJS resolver supports using invalid package name used with bare specifier.

Example:

require('@foo')

This is not supported by ESM resolver. Vite core won't support this.

virtual packages: single file

CJS resolver supports using a single file instead of a directory containing a package.

Example:

- node_modules
  - foo.js
- file.js

// file.js
require('foo') // this resolves to node_modules/foo.js

This is not supported by ESM resolver. Vite core won't support this.

nested package.json

CJS resolver supports package.json inside a directory in a package.

Example:

- node_modules
  - foo
    - bar
      - package.json # main field has "main.js"
      - main.js
    - package.json
- file.js

// file.js
require('foo/bar') // resolves to node_modules/foo/bar/main.js

This is not supported by ESM resolver. Vite core does support this.

global node_modules paths (NODE_PATH)

CJS resolver supports global node_modules paths (NODE_PATH).

This is not supported by ESM resolver as you can see from the spec. Also will not likely be supported.

Vite core won't support this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment