loader: implement package maps

[arcanis]

This PR adds a new --experimental-package-map=<path> flag letting Node.js resolve packages using a static JSON file instead of walking node_modules directories.

node --experimental-package-map=./package-map.json app.js

Why?

The node_modules resolution algorithm predates npm and its clear definition of the concept of packages. It works well enough and is widely supported, but has known issues:

• Phantom dependencies - packages can accidentally import things they don't declare, because hoisting makes transitive dependencies visible

• Peer dependency resolution is broken in monorepos - if website-v1 uses react@18 and website-v2 uses react@19, and both use a shared component-lib with React as a peer dep, there's no node_modules layout that resolves correctly. The shared lib always gets whichever React was hoisted.

• Hoisting is lossy - runtimes can't tell if an import is legitimate or accidental

• Resolution requires I/O - you have to hit the filesystem to resolve packages

Package managers have tried workarounds (pnpm symlinks, Yarn PnP), but are either limited by what the filesystem itself can offer (like symlinks) or by their complexity and lack of standardization (like Yarn PnP). This PR offers a mechanism for such tools to solve the problems listed above in tandem with Node.js.

How it works

A package-map.json declares packages, their locations (relative to the package map), and what each can import:

{
  "packages": {
    "my-app": {
      "path": "./src",
      "dependencies": {
        "lodash": "lodash",
        "react": "react"
      }
    },
    "lodash": {
      "path": "./node_modules/lodash"
    },
    "react": {
      "path": "./node_modules/react"
    }
  }
}

When resolving a bare specifier:

1. Find which package contains the importing file (ideally by keeping track of package IDs during resolution, but for now by checking paths)
2. Look up the specifier in that package's dependencies
3. If found, resolve to the target's path
4. If not found but exists elsewhere in the map → ERR_PACKAGE_MAP_ACCESS_DENIED
5. If not in the map at all → MODULE_NOT_FOUND

Compatibility

An important aspect of the package maps feature that separates it from competing options like Yarn PnP is its builtin compatibility with node_modules installs. Package managers can generate both node_modules folders AND package-map.json files, with the later referencing paths from the former.

Tools that know how to leverage package-map.json can then use this pattern for both static package resolution and strict dependency checks (with optional fallbacks to hoisting if they just wish to use the package map information to emit warnings rather than strict errors), whereas tools that don't will fallback to the classical node_modules resolution.

Differences with import maps

Issue #49443 requested to implement import maps. In practice these aren't a good fit for runtimes like Node.js for reasons described here and which can be summarized as: import maps take full ownership of the resolution pipeline by spec, thus preventing implementing additional runtime-specific behaviours such as exports or imports fields.

This PR comes as close from implementing import maps as possible but with a very light difference in design making it possible to stay compatible with other Node.js resolution features.

Why not a loader?

The ecosystem now has to deal with a variety of third-party resolvers, most of them not implementing the loader API for many different reasons: too complex, turing-complete, or dependent on a JS runtime.

After I've been following this path for more than six years I can confidently say that loaders would work for Node.js itself but wouldn't be standard enough to be included in at least some of those popular third-party tools.

Questions

• The current implementation makes package maps strict: if they find an issue, they throw and refuse the resolution. Should we instead delegate to the default resolution unless an additional --experimental-strict-package-maps is set? Or via a strict field in package-map.json.

[nodejs-github-bot]

Review requested:

• @nodejs/config
• @nodejs/loaders

[zkochan]

I like the idea, it would greatly reduce the amount of filesystem operations that pnpm has to do in order to create an isolated node_modules layout using symlinks.

I also suggested arcanis to possibly go one layer deeper and allow to map the individual files of packages. This would allow to map node_modules directly from a content-addressable store (that consists of package files). Of course, that would increase the size of the file several times but it would also make installation even faster.

[codecov]

Codecov Report

❌ Patch coverage is 99.23664% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.70%. Comparing base (66a687f) to head (1473492).
⚠️ Report is 74 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/modules/cjs/loader.js	96.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62239      +/-   ##
==========================================
+ Coverage   89.66%   89.70%   +0.04%     
==========================================
  Files         676      677       +1     
  Lines      206462   207084     +622     
  Branches    39533    39653     +120     
==========================================
+ Hits       185128   185773     +645     
+ Misses      13461    13440      -21     
+ Partials     7873     7871       -2     

Files with missing lines	Coverage Δ
lib/internal/errors.js	97.63% <100.00%> (+0.01%)	⬆️
lib/internal/modules/esm/resolve.js	99.05% <100.00%> (+0.10%)	⬆️
lib/internal/modules/package_map.js	100.00% <100.00%> (ø)
src/node_options.cc	76.47% <100.00%> (+0.02%)	⬆️
src/node_options.h	97.93% <ø> (ø)
lib/internal/modules/cjs/loader.js	98.24% <96.00%> (+0.09%)	⬆️

... and 55 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[aduh95]

This seems quite close to the importmap HTML feature, but using a different syntax. Have you considered reusing the same syntax, or at least a compatible JSON structure?

[arcanis]

I did, but felt that the semantics were too different; import maps have two fields:

• the imports field is a global resolution map, keyed by bare identifiers. It wouldn't work for packages as that field is a flat map of all packages in the project, and thus must be keyed by arbitrary package IDs to allow for multiple packages sharing the same name (ie multiple versions of a same package in the same dependency tree).

• the scopes field is keyed by filesystem path. This is a problem because it precludes a same folder from having multiple package IDs each with their own dependency set, necessary to represent peer dependencies with workspaces.

Neither of those match the semantics we need, and reusing them just for their name but with different semantics would have been imo misleading for third-party resolver implementors.

[jasnell]

Love it. I'll try to give a detailed review on the flight home today if the in flight wifi treats me kindly.

[bakkot]

What happens if two packages define the exact same path? An error, presumably, given that the algorithm relies on being able to determine for each path which package it belongs to? Needs a test in any case.

[arcanis]

What happens if two packages define the exact same path? An error, presumably, given that the algorithm relies on being able to determine for each path which package it belongs to? Needs a test in any case.

I'll follow-up with a separate improvement to key module instances per both their path and their package IDs (it's key to solve the peer dependency problem I mentioned in the PR description), but for this iteration only one package ID per path is supported. I updated the code to throw an error accordingly.

[arcanis]

@guybedford @avivkeller can I get another review? once this land I'll start looking at a prototype for generating package maps in package managers, and the package ID follow-up

[ljharb]

How does this work given the module cache? Wont the first one to load’s react version “win”?

[arcanis]

Yes, that's why it's not implemented in this PR (it throws should this case happen), and will be implemented as a follow-up: #62239 (comment) (still I want it to be documented as third-party tools reading package maps better know about this early in the implementation)

[bakkot]

What happens when there's symlinks in the specified paths?

From the current implementation it looks like it basically breaks. getKeyForPath relies on being able to determine which package in the package map contains a given file, which it does by walking up from the file and checking if each ancestor directory appears as a path in the package map. But if the path in the package map points to a symlink, it will never resolve.

You could sort of fix this by resolving symlinks in the package map (at the cost of a lot of file system operations during startup), but then you have the problem that the "longest path containing a file" heuristic is now ambiguous: you could have a file /a/b/c/index.js and symlinks /foo/bar -> /a and /baz -> /a/b/c, and package map

{
  "packages": {
    "my-app": {
      "path": "./src",
      "dependencies": {
        "foo": "foo",
        "baz": "baz"
      }
    },
    "foo": {
      "path": "/foo/bar"
    },
    "baz": {
      "path": "/baz"
    }
  }
}

and then /a/b/c/index.js is in foo if "longest path" is defined according to the package map but in bar if "longest path" is defined according to the file system.

I don't have a good intuition for what the right thing to do here is.

[arcanis]

What happens when there's symlinks in the specified paths?

It depends where the symlink is:

• if the symlink is an ancestor of the package map file it should be realpath'd, just like Node.js calls realpath on paths it uses for resolution. Adding a test to make sure of that.

• if the symlink is listed in path (for example "path": "./path/to/symlink"), it'll never match since Node.js calls realpath on each module path (so it would never pass ./path/to/symlink to the resolve function, but instead ./path/to/real/path, which wouldn't match). I'd also tend not to realpath the path field as:

  1. it changes in unpredictable ways the paths as initially intended
  2. whichever tool created the package map can realpath them itself
  3. in the event we later support loading package maps from urls, realpath wouldn't make sense

[ruyadorno]

Is it possible for @arcanis or someone else familiar with the work to come to the next TSC meeting to talk a little about this implementation? I have two concerns with landing this at the moment:

• Awareness: like mentioned in the "Why?" section of its description, this PR is introducing a complete new alternative to the more-than-a-decade old module resolution system, have APM folks been looped in? were the other adjacents WG consulted? @nodejs/package-maintenance @nodejs/tooling
• Import maps: Is the current implementation going to create an irremediable compatibility with that standard? Can this use some help from the @nodejs/wintercg folks to help standardize this so that other runtimes may also implement support in the future?

That said, thanks @arcanis for taking the time to work on it! I feel like the runtime definitely needs to innovate on this and sorry to be potentially slowing things down in the immediate time but hopefully it's to make sure we land on a solution that will last! ✌️

[wesleytodd]

I have been looking for someone who wanted to take over and help get #49443 over the finish line. Maybe this would be a good opportunity to start a thread in with @nodejs/wintercg, come up with the technical and UX goals we have for this feature. I think we need to decide if we need spec changes (to pursue via the standards process) or if we can find workarounds that maintain spec compliance. @arcanis happy to work with you on this if you are interested.

[arcanis]

Is it possible for @arcanis or someone else familiar with the work to come to the next TSC meeting to talk a little about this implementation?

Sure, happy to, please invite me to the next meeting.

I also discussed it a little while ago with folks at the WinterTC and it wasn't clear at the time whether it was worth a multi-vendor discussion at that stage. So I figured that since this is behind --experimental-* we'd have room to iterate, but let me open a thread nonetheless.

Is the current implementation going to create an irremediable compatibility with that standard

The designs serve different goals. The way import maps are keyed makes it impossible to support very common dependency graphs, causing package managers to generate semantically incorrect installs or rely on features like inject or virtual paths which add complexity and come with their own trade-offs.

That's not to say import maps can't be implemented in Node.js as well, but their design limits them to solve more web-specific use cases that wouldn't satisfy the practical problems our local package managers set out to address.