Node.js 26.4 quietly shipped one of the more practical module-resolution experiments in years: package maps. If you maintain a monorepo, fight phantom dependencies, or keep explaining why node_modules hoisting behaves the way it does, this is worth testing now and shipping later.
Package maps are not a replacement for
package.jsonexports. They are a static dependency graph that lets Node resolve bare package imports without depending on the physical shape ofnode_modules.
1. Know what changed in 26.4
Node.js 26.4.0 landed on June 24, 2026, and its notable changes include loader: implement package maps. The feature is documented as Stability 1, which means experimental, and it only turns on when you pass --experimental-package-map.
That matters. This is not something to enable across production services because a release blog made it sound finished. It is a good candidate for local experiments, package-manager prototypes, CI checks, and monorepo tooling where strict dependency resolution is exactly the point.
Run it like this:
node --experimental-package-map=./package-map.json ./packages/app/index.js2. Understand the shape of the file
A package map is a JSON file with a top-level packages object. Each entry gets a package ID, a url pointing at the package location, and optionally a dependencies object that maps import names to other package IDs.
{
"packages": {
"app": {
"url": "./packages/app",
"dependencies": {
"@acme/utils": "utils",
"@acme/ui": "ui"
}
},
"utils": {
"url": "./packages/utils"
},
"ui": {
"url": "./packages/ui"
}
}
}With that map, a file inside packages/app can import @acme/utils and @acme/ui because those names are explicitly listed under app.dependencies. If it imports an undeclared bare package, Node throws MODULE_NOT_FOUND instead of accidentally finding a hoisted dependency.
3. Use it to catch phantom dependencies
The most immediately useful test is dependency isolation. Today, a workspace package can often import a package it never declared because the dependency happens to be hoisted somewhere above it. That passes locally until a different install layout, Docker image, package manager, or CI cache exposes the mistake.
Package maps make that mistake visible. The importing package gets only the bare specifiers listed in its dependencies map. Relative imports, absolute paths, URLs, and built-in modules such as node:fs keep their normal behavior, so you can focus on package-to-package boundaries instead of rewriting every import.
A useful local check looks like this:
node --experimental-package-map=./node_modules/.package-map.json ./scripts/smoke-imports.mjsThe future-friendly version is package-manager generated. The pull request that introduced the feature explicitly describes package managers generating both a normal node_modules tree and a package-map.json file that points into it. Old tools keep working against node_modules; newer tools can use the map for strict checks.
4. Do not confuse package maps with browser import maps
The names are close, but the design goal is different. Browser import maps take over module resolution. Node package maps feed a package location into Node's existing resolver, so Node can still honor regular package behavior such as exports, imports, and index resolution.
That difference is why the feature fits Node better than a straight import-map clone. You are not declaring every file path your app can import. You are declaring package ownership and allowed package relationships, then letting Node finish the normal resolution work from the target package location.
5. Keep the first experiment boring
Start with one small workspace package, not the whole repository. Generate or hand-write a minimal map for the app package and two internal dependencies. Then run a smoke script that imports the public entry points you expect to work.
import "@acme/utils";
import "@acme/ui";
console.log("package map smoke test passed");If it passes, add one intentionally undeclared import and confirm that Node fails. That negative test is the point: a package map that only proves the happy path is less useful than one that catches the dependency leak you already suspected.
6. Watch the limitations before building around it
The current documentation calls out real constraints. A package map is a single static file, dynamic configuration is not supported, circular dependency detection is not handled by the package-map resolver, and the map loads synchronously at startup.
There are also practical ecosystem questions. The implementation discussion calls package-manager integration the intended direction, and it notes compatibility with node_modules installs as a major advantage. Until npm, pnpm, Yarn, test runners, bundlers, and language servers converge on the same generated map story, the smart move is to treat package maps as a strictness experiment rather than a migration plan.
7. A reasonable adoption path
Use package maps first as a CI-only diagnostic for one workspace. If that catches real undeclared imports, fix the manifests and keep the smoke test. If it creates noise, do not force it into the runtime path yet.
The long-term upside is clear: explicit package boundaries without making every tool abandon node_modules at once. The short-term rule is just as clear: keep it behind --experimental-package-map, use it to learn where your dependency graph is lying, and wait for package managers to make the map generation boring.