GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — loader: implement package maps · nodejs/node@b3cfb55

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
  • doc
    • api
      • cli.md
      • errors.md
      • esm.md
      • modules.md
      • packages.md
    • node.1
  • lib/internal
    • errors.js
    • modules
      • cjs
        • loader.js
      • esm
        • resolve.js
      • package_map.js
  • src
    • node_options.cc
    • node_options.h
  • test
    • es-module
      • test-esm-package-map-basic.mjs
      • test-esm-package-map-boundaries.mjs
      • test-esm-package-map-errors.mjs
      • test-esm-package-map-exports.mjs
      • test-esm-package-map-flag.mjs
      • test-esm-package-map-paths.mjs
      • test-esm-package-map-symlink.mjs
      • test-esm-package-map-version-fork.mjs
    • fixtures/package-map
      • app-18
        • index.js
        • package.json
      • app-19
        • index.js
        • package.json
      • component-lib
        • index.js
        • package.json
      • dep with spaces
        • index.js
        • package.json
      • dep-a
        • index.cjs
        • index.js
        • lib
          • util.js
        • package.json
      • dep-b
        • index.js
        • package.json
      • nameless-pkg
        • index.js
      • nested-project
        • package-map-external-deps.json
        • src
          • .gitkeep
      • not-a-dep
        • index.js
        • package.json
      • package-map-duplicate-path.json
      • package-map-https-path.json
      • package-map-invalid-schema.json
      • package-map-invalid-syntax.json
      • package-map-longest-path.json
      • package-map-missing-dep.json
      • package-map-path-prefix.json
      • package-map-url-encoded-spaces.json
      • package-map-version-fork.json
      • package-map.json
      • pkg-other
        • index.js
        • package.json
      • pkg
        • index.cjs
        • index.js
        • package.json
      • react-18
        • index.js
        • package.json
      • react-19
        • index.js
        • package.json
      • root
        • index.js
        • node_modules/inner
          • index.cjs
          • index.js
          • package.json
        • package.json
    • parallel
      • test-bootstrap-modules.js
      • test-package-map-cli.js
      • test-require-package-map.js

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Dismiss banner
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎doc/api/cli.md‎

Copy file name to clipboardExpand all lines: doc/api/cli.md
+23Lines changed: 23 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -1148,6 +1148,27 @@ added:
11481148
11491149
Enable experimental support for the network inspection with Chrome DevTools.
11501150

1151+
### `--experimental-package-map=<path>`
1152+
1153+
<!-- YAML
1154+
added: REPLACEME
1155+
-->
1156+
1157+
> Stability: 1 - Experimental
1158+
1159+
Enable experimental package map resolution. The `path` argument specifies the
1160+
location of a JSON configuration file that defines package resolution mappings.
1161+
1162+
```bash
1163+
node --experimental-package-map=./package-map.json app.js
1164+
```
1165+
1166+
When enabled, bare specifier resolution consults the package map for resolution.
1167+
This allows explicit control over which packages can import which dependencies.
1168+
1169+
See [Package maps][] for details on the configuration file format and
1170+
resolution algorithm.
1171+
11511172
### `--experimental-print-required-tla`
11521173

11531174
<!-- YAML
@@ -3579,6 +3600,7 @@ one is included in the list below.
35793600
* `--experimental-json-modules`
35803601
* `--experimental-loader`
35813602
* `--experimental-modules`
3603+
* `--experimental-package-map`
35823604
* `--experimental-print-required-tla`
35833605
* `--experimental-quic`
35843606
* `--experimental-require-module`
@@ -4170,6 +4192,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
41704192
[Navigator API]: globals.md#navigator
41714193
[Node.js issue tracker]: https://github.com/nodejs/node/issues
41724194
[OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html
4195+
[Package maps]: packages.md#package-maps
41734196
[Permission Model]: permissions.md#permission-model
41744197
[REPL]: repl.md
41754198
[ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage
Collapse file

‎doc/api/errors.md‎

Copy file name to clipboardExpand all lines: doc/api/errors.md
+72Lines changed: 72 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -2499,6 +2499,77 @@ A given value is out of the accepted range.
24992499
The `package.json` [`"imports"`][] field does not define the given internal
25002500
package specifier mapping.
25012501

2502+
<a id="ERR_PACKAGE_MAP_EXTERNAL_FILE"></a>
2503+
2504+
### `ERR_PACKAGE_MAP_EXTERNAL_FILE`
2505+
2506+
<!-- YAML
2507+
added: REPLACEME
2508+
-->
2509+
2510+
A module attempted to resolve a bare specifier using the [package map][], but
2511+
the importing file is not located within any package defined in the map.
2512+
2513+
```console
2514+
$ node --experimental-package-map=./package-map.json /tmp/script.js
2515+
Error [ERR_PACKAGE_MAP_EXTERNAL_FILE]: Cannot resolve "dep-a" from "/tmp/script.js": file is not within any package defined in /path/to/package-map.json
2516+
```
2517+
2518+
To fix this error, ensure the importing file is inside one of the package
2519+
directories listed in the package map, or add a new package entry whose `url`
2520+
covers the importing file.
2521+
2522+
<a id="ERR_PACKAGE_MAP_INVALID"></a>
2523+
2524+
### `ERR_PACKAGE_MAP_INVALID`
2525+
2526+
<!-- YAML
2527+
added: REPLACEME
2528+
-->
2529+
2530+
The [package map][] configuration file is invalid. This can occur when:
2531+
2532+
* The file does not exist at the specified path.
2533+
* The file contains invalid JSON.
2534+
* The file is missing the required `packages` object.
2535+
* A package entry is missing the required `url` field.
2536+
* Two package entries have the same `url` value.
2537+
2538+
```console
2539+
$ node --experimental-package-map=./missing.json app.js
2540+
Error [ERR_PACKAGE_MAP_INVALID]: Invalid package map at "./missing.json": file not found
2541+
```
2542+
2543+
<a id="ERR_PACKAGE_MAP_KEY_NOT_FOUND"></a>
2544+
2545+
### `ERR_PACKAGE_MAP_KEY_NOT_FOUND`
2546+
2547+
<!-- YAML
2548+
added: REPLACEME
2549+
-->
2550+
2551+
A package's `dependencies` object in the [package map][] references a package
2552+
key that is not defined in the `packages` object.
2553+
2554+
```json
2555+
{
2556+
"packages": {
2557+
"app": {
2558+
"url": "./app",
2559+
"dependencies": {
2560+
"foo": "nonexistent"
2561+
}
2562+
}
2563+
}
2564+
}
2565+
```
2566+
2567+
In this example, `"nonexistent"` is referenced as a dependency target but not
2568+
defined in `packages`, which will throw this error.
2569+
2570+
To fix this error, ensure all package keys referenced in `dependencies` values
2571+
are defined in the `packages` object.
2572+
25022573
<a id="ERR_PACKAGE_PATH_NOT_EXPORTED"></a>
25032574

25042575
### `ERR_PACKAGE_PATH_NOT_EXPORTED`
@@ -4531,6 +4602,7 @@ An error occurred trying to allocate memory. This should never happen.
45314602
[domains]: domain.md
45324603
[event emitter-based]: events.md#class-eventemitter
45334604
[file descriptors]: https://en.wikipedia.org/wiki/File_descriptor
4605+
[package map]: packages.md#package-maps
45344606
[relative URL]: https://url.spec.whatwg.org/#relative-url-string
45354607
[self-reference a package using its name]: packages.md#self-referencing-a-package-using-its-name
45364608
[special scheme]: https://url.spec.whatwg.org/#special-scheme
Collapse file

‎doc/api/esm.md‎

Copy file name to clipboardExpand all lines: doc/api/esm.md
+8Lines changed: 8 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -949,6 +949,12 @@ The default loader has the following properties
949949
* Fails on unknown extensions for `file:` loading
950950
(supports only `.cjs`, `.js`, and `.mjs`)
951951
952+
When the [`--experimental-package-map`][] flag is enabled, bare specifier
953+
resolution first consults the package map configuration. If the importing
954+
module is within a mapped package and the specifier matches a declared
955+
dependency, the package map resolution takes precedence. See [Package maps][]
956+
for details.
957+
952958
### Resolution algorithm
953959
954960
The algorithm to load an ES module specifier is given through the
@@ -1312,13 +1318,15 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
13121318
[Loading ECMAScript modules using `require()`]: modules.md#loading-ecmascript-modules-using-require
13131319
[Module customization hooks]: module.md#customization-hooks
13141320
[Node.js Module Resolution And Loading Algorithm]: #resolution-algorithm-specification
1321+
[Package maps]: packages.md#package-maps
13151322
[Source Phase Imports]: https://github.com/tc39/proposal-source-phase-imports
13161323
[Terminology]: #terminology
13171324
[Text modules]: #text-modules
13181325
[URL]: https://url.spec.whatwg.org/
13191326
[WebAssembly JS String Builtins Proposal]: https://github.com/WebAssembly/js-string-builtins
13201327
[`"exports"`]: packages.md#exports
13211328
[`"type"`]: packages.md#type
1329+
[`--experimental-package-map`]: cli.md#--experimental-package-mappath
13221330
[`--input-type`]: cli.md#--input-typetype
13231331
[`data:` URLs]: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data
13241332
[`export`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export
Collapse file

‎doc/api/modules.md‎

Copy file name to clipboardExpand all lines: doc/api/modules.md
+36-15Lines changed: 36 additions & 15 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -353,8 +353,12 @@ require(X) from module at path Y
353353
4. If X begins with '#'
354354
a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))
355355
5. LOAD_PACKAGE_SELF(X, dirname(Y))
356-
6. LOAD_NODE_MODULES(X, dirname(Y))
357-
7. THROW "not found"
356+
6. If a package map PACKAGE_MAP exists,
357+
a. Find the package ID for the package owning Y
358+
1. Let PARENT_PACKAGE_ID be FIND_PACKAGE_ID(dirname(Y), PACKAGE_MAP)
359+
b. LOAD_PACKAGE_MAP(X, PARENT_PACKAGE_ID, PACKAGE_MAP)
360+
7. LOAD_NODE_MODULES(X, dirname(Y))
361+
8. THROW "not found"
358362
359363
MAYBE_DETECT_AND_LOAD(X)
360364
1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
@@ -398,9 +402,11 @@ LOAD_AS_DIRECTORY(X)
398402
2. LOAD_INDEX(X)
399403
400404
LOAD_NODE_MODULES(X, START)
401-
1. let DIRS = NODE_MODULES_PATHS(START)
402-
2. for each DIR in DIRS:
403-
a. LOAD_PACKAGE_EXPORTS(X, DIR)
405+
1. Try to interpret X as a combination of NAME and SUBPATH where the name
406+
may have a @scope/ prefix and the subpath begins with a slash (`/`).
407+
2. let DIRS = NODE_MODULES_PATHS(START)
408+
3. for each DIR in DIRS:
409+
a. LOAD_PACKAGE_EXPORTS(SUBPATH, DIR/NAME)
404410
b. LOAD_AS_FILE(DIR/X)
405411
c. LOAD_AS_DIRECTORY(DIR/X)
406412
@@ -415,6 +421,25 @@ NODE_MODULES_PATHS(START)
415421
d. let I = I - 1
416422
5. return DIRS + GLOBAL_FOLDERS
417423
424+
FIND_PACKAGE_ID(PATH, PACKAGE_MAP)
425+
1. Find the PACKAGE_ID for the entry whose "path" is a parent directory of PATH
426+
2. If multiple entries are found, THROW "ambiguous resolution"
427+
3. If no entry was found, THROW "external file".
428+
4. return PACKAGE_ID
429+
430+
LOAD_PACKAGE_MAP(X, PARENT_PACKAGE_ID, PACKAGE_MAP)
431+
1. Try to interpret X as a combination of NAME and SUBPATH where the name
432+
may have a @scope/ prefix and the subpath begins with a slash (`/`).
433+
2. Find the package map entry for key PARENT_PACKAGE_ID
434+
3. Look up NAME in the entry's "dependencies" map.
435+
4. If NAME is not found, THROW "not found".
436+
5. Let TARGET be PACKAGE_MAP.packages[dependencies[name]]
437+
6. Let PACKAGE_PATH be the resolved path of TARGET.
438+
7. LOAD_PACKAGE_EXPORTS(SUBPATH, PACKAGE_PATH)
439+
8. LOAD_AS_FILE(PACKAGE_PATH/SUBPATH)
440+
9. LOAD_AS_DIRECTORY(PACKAGE_PATH/SUBPATH)
441+
10. THROW "not found"
442+
418443
LOAD_PACKAGE_IMPORTS(X, DIR)
419444
1. Find the closest package scope SCOPE to DIR.
420445
2. If no scope was found, return.
@@ -426,19 +451,15 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
426451
CONDITIONS) defined in the ESM resolver.
427452
6. RESOLVE_ESM_MATCH(MATCH).
428453
429-
LOAD_PACKAGE_EXPORTS(X, DIR)
430-
1. Try to interpret X as a combination of NAME and SUBPATH where the name
431-
may have a @scope/ prefix and the subpath begins with a slash (`/`).
432-
2. If X does not match this pattern or DIR/NAME/package.json is not a file,
433-
return.
434-
3. Parse DIR/NAME/package.json, and look for "exports" field.
435-
4. If "exports" is null or undefined, return.
436-
5. If `--no-require-module` is not enabled
454+
LOAD_PACKAGE_EXPORTS(SUBPATH, PACKAGE_DIR)
455+
1. Parse PACKAGE_DIR/package.json, and look for "exports" field.
456+
2. If "exports" is null or undefined, return.
457+
3. If `--no-require-module` is not enabled
437458
a. let CONDITIONS = ["node", "require", "module-sync"]
438459
b. Else, let CONDITIONS = ["node", "require"]
439-
6. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
460+
4. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(PACKAGE_DIR), "." + SUBPATH,
440461
`package.json` "exports", CONDITIONS) defined in the ESM resolver.
441-
7. RESOLVE_ESM_MATCH(MATCH)
462+
5. RESOLVE_ESM_MATCH(MATCH)
442463
443464
LOAD_PACKAGE_SELF(X, DIR)
444465
1. Find the closest package scope SCOPE to DIR.

0 commit comments

Comments
0 (0)
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.