Store and layout
How Nub arranges node_modules and where it keeps packages on disk — the shared virtual store, the flat and project-local layouts, store and cache locations, and pruning.
By default, Nub links each package version once per machine, into a shared virtual store, and each project's node_modules symlinks into it. Direct dependencies sit at the top level, and an undeclared (phantom) import fails instead of resolving by accident.
my-app/
└── node_modules/
├── ms → ~/.cache/nub/pm/store/…/ms@2.1.3
└── react → ~/.cache/nub/pm/store/…/react@19.2.0Layouts
The default is isolated under every incumbent. Two .npmrc settings change it:
# keep the isolated layout, but put the store inside the project
enableGlobalVirtualStore=false
# a flat, npm-style tree with no virtual store
node-linker=hoistedThe same choice is the linker field in nub.jsonc: global-virtual-store for the shared store (the default), isolated for a project-local one, or hoisted for a flat tree.
{
// ...
"install": {
"linker": "isolated"
}
}Flat layout
A flat node_modules, with no virtual store, is npm's layout. It suits a project that relies on phantom dependencies. Set node-linker=hoisted in .npmrc, or pass the flag for one command:
nub install --node-linker hoistedNub reads node-linker from .npmrc under every incumbent. Files still come from the global content store by reflink or hardlink, so a flat tree costs little extra disk.
Layout versus hoist patterns
The node-linker setting picks the layout. The hoist, shamefully-hoist, and public-hoist-pattern settings are separate: they lift packages to the top level within the isolated layout and keep the virtual store.
Shared vs per-project store
Outside CI, the virtual store is shared across projects: a package version materializes once per machine and every project links to it. The links point outside the project, so a node_modules copied to another machine does not resolve.
In CI, and under nub ci, each project gets its own virtual store at node_modules/.store/, with real directories and relative links. That tree survives a Docker COPY --from into a fresh image. Force it for any install:
enableGlobalVirtualStore=falseThe project-local store has the same shape as pnpm's node_modules/.pnpm/, but the two are not shared, so alternating between the tools relinks the tree.
Read the full docs on pnpm.io.
Ejection
Some packages and tools break when a dependency's real path is outside the project. Nub detects them and moves only those into the project, so the rest of the tree keeps sharing:
| What breaks | Example | What Nub does |
|---|---|---|
| A package importing a backend it never declares | @hookform/resolvers/zod reaching your zod | Materializes the adapter into the project |
| A package writing generated code beside itself | Prisma's postinstall running prisma generate | Materializes the package so generate stays project-local |
| A package whose dependency is overridden to a local copy | overrides pointing is-number at file:./vendor/is-number | Materializes the package that depends on it, so it can reach the copy |
| A bundler or asset server that resolves by real path | Next.js; Metro, in bare React Native and Expo before SDK 56 | Gives the project a self-contained store |
| A dev server that gates real-path access by allow-list | Vite; Remix 3's asset server | Writes node_modules/.modules.yaml, which both read — no config change |
Add packages of your own in .npmrc or nub.jsonc:
# a package whose presence gives the whole project its own store
disableGlobalVirtualStoreForPackages=my-bundler # comma-separated{
// ...
"install": {
"linker": {
"strategy": "global-virtual-store",
// written into the project as real directories
"eject": ["electron", "@company/native-*"]
}
}
}Hoisting and paths
The remaining layout settings are pnpm's, set in .npmrc:
hoist-pattern=lodash
public-hoist-pattern=@types/*
shamefully-hoist=true
hoist-workspace-packages=false
hoisting-limits=workspaces
modules-dir=vendor_modules
virtual-store-dir=.storeRead the full docs on pnpm.io.
In nub.jsonc, publicHoist lifts packages to the project's top-level node_modules, for tools like TypeScript that look for @types/* there. Under the isolated strategy, the hoist option fills the hidden fallback tree at node_modules/.store/node_modules/, which dependencies reach when they import something they never declared:
{
// ...
"install": {
"publicHoist": ["@types/*"],
"linker": {
"strategy": "isolated",
"hoist": ["*eslint*", "@types/*"] // true, false, or a pattern list
}
}
}The hoist option is valid only under isolated, and eject only under global-virtual-store. Naming one under the other strategy is an error.
Disk locations
Nub keeps package files and download caches outside the project, in these directories.
Content store
Package files are deduplicated by content hash in a global store at $XDG_DATA_HOME/nub/store/v1/ (default ~/.local/share/nub/store/v1/). A given package version is on disk once, shared across projects.
$ nub store path
/Users/you/.local/share/nub/store/v1Files reach node_modules by reflink on APFS and btrfs, hardlink on ext4, or copy as a fallback.
Relocating the store
The store location is the store-dir setting. Set it persistently with nub config set, which writes the project's config:
$ nub config set store-dir /srv/nub-store
set store-dir=/srv/nub-store (/home/you/app/.npmrc)
$ nub store path
/srv/nub-store/v1For a single run, such as a CI job or a test sandbox, use the environment variable:
$ npm_config_store_dir=/tmp/scratch-store nub installSources, highest first:
npm_config_store_dir(environment)storeDirinpnpm-workspace.yaml(pnpm incumbent)store-dirin the project.npmrcstore-dirin the user~/.npmrc$XDG_DATA_HOME/nub/store/(default)
Nub appends the v1/ suffix to the configured directory. A relative path resolves against the project root.
Cache directory
Registry metadata and the shared virtual store live in a cache at $XDG_CACHE_HOME/nub/pm/ (default ~/.cache/nub/pm/). Move it, for example to a faster volume or a CI cache mount, with cache-dir:
cache-dir=/mnt/fast/nub-cacheTwo environment variables set the same thing, and both outrank the file:
# neutral — npm and pnpm read it too
npm_config_cache_dir=/mnt/fast/nub-cache nub install
# Nub's own spelling, which wins over the above
NUB_CACHE_DIR=/mnt/fast/nub-cache nub installPrint the effective value:
$ npm_config_cache_dir=/mnt/fast/nub-cache nub config get cache-dir
/mnt/fast/nub-cacheKeep cache-dir on the same volume as store-dir. The shared virtual store hardlinks out of the content store, and a hardlink cannot cross filesystems, so a split falls back to a per-file copy and Nub warns.
A few caches stay at the platform default regardless: the advisory database, the bootstrapped node-gyp, git clones, and the registry behind nub link -g.
Offline installs
When the store already holds every package, an install relinks from it with no network access:
nub install # offline when the store has every package
nub install --offline # force offline
nub install --prefer-offline # try the cache firstWhen Nub provisioned the project's Node, a native addon build also works offline: Nub fills the node-gyp header cache from that Node. On Windows, node-gyp still downloads the headers, because the official Node zip carries none.
Reclaiming disk space
A store entry is keyed by its whole resolved dependency graph, so one bump leaves several old entries behind. Remove them with a prune:
nub store prunePruned 4 packages (0.1 MB) from the global virtual store
Pruned 1 stale project record from the global virtual store registry
Pruned 4 files (0.0 MB) from the storeA prune keeps every entry a registered project still links to, directly or through another entry, and removes the rest. Every install registers its project, including one that reports no work to do. A registered project whose directory is gone stops counting, and the prune drops its record. Pass --dry-run to print the plan without removing anything, or --dry-run --json for JSON.
The extracted-tree cache, the copy of each package that the linker clones into projects, is held for 30 days. The first prune to find an entry unreferenced reports it, and only a prune 30 days later removes it. An install that needs the entry clears the hold.
Holding 30029 entries of the extracted-tree cache unreferenced for 30 days
before removal. Install in any project that still needs them and they are
kept.With no projects registered at all, a prune skips that cache:
No projects are registered against the store; skipping the extracted-tree
cache. Run an install in each project you want kept, then prune again.GYP-based native builds
Some packages that compile native code with node-gyp fail to build under the isolated layout. The trigger is a binding.gyp that names another package as a GYP build-file dependency:
{
"targets": [
{
"dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"]
}
]
}GYP resolves such a reference one level short of its target when it points outside the package directory, as it does in any non-flat node_modules. The build either fails with a Python FileNotFoundError naming a .target.mk path, or writes a duplicate tree next to the intended one. Install that project flat:
nub install --node-linker hoistedHow it works
The shared layout rests on two mechanisms: store entries that link to each other, and a scan for imports a package never declared.
One symlink per package
Each store entry holds a package version's real files plus symlinks to its declared dependencies, and the project's node_modules symlinks each package straight into the store. Two properties follow:
- Warm installs scale with package count, not file count. Linking a project takes one symlink per package instead of one hardlink or copy per file.
- The store is sealed. Node resolves a symlink to its real path before loading, so code in the store resolves imports from inside its own entry: its declared dependencies and nothing else.
Widely used packages import phantom dependencies, packages they never declare, and a sealed store breaks them. The blog post how we built a 5x faster package manager covers the history.
Phantom detection
As each tarball enters the store, Nub parses the version's published code with Oxc. It walks the module graph from the package's exports, main, and bin entry points and checks every static, unguarded import against the declared dependencies. Each verdict is cached machine-wide per content fingerprint.
At link time, a flagged package is ejected: hardlinked into the project as real files, so its resolution walk passes through the project, where Nub links the undeclared target. Everything that transitively imports the flagged package is ejected with it, so the package loads from one path. The rest of the tree stays symlinked. The toolchains that need a whole project-local store are listed under ejection.
Performance
The benchmark is a warm reinstall of a 1,168-package tree: store populated, lockfile present, node_modules removed between runs.
warm install · 1168 packages · Linux (ubuntu-latest)
hyperfine, 25 runs / 6 warmup, near-idle ubuntu-latest runner · bun 1.3.14, pnpm 10.34.4, npm on Node 24. View benchmark →