Skip to content

docs: rename virtual store to dependency graph store #683

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: rename virtual store to dependency graph store #683

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4470d42
docs: rename virtual store to dependency graph store
zkochan Jun 28, 2025
1eeb0df
docs: rename virtual store to dependency graph store
zkochan Jun 28, 2025
142982d
docs: rename virtual store to dependency graph store
zkochan Jun 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/cli/fetch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ id: fetch
title: pnpm fetch
---

Fetch packages from a lockfile into virtual store, package manifest is ignored.
Fetch packages from a lockfile into dependency graph store, package manifest is ignored.

## Usage scenario

Expand Down Expand Up @@ -82,7 +82,7 @@ As you can see, the Dockerfile has to be updated when you add or remove
sub-packages.

`pnpm fetch` solves the above problem perfectly by providing the ability
to load packages into the virtual store using only information from a lockfile and a configuration file (`pnpm-workspace.yaml`).
to load packages into the dependency graph store using only information from a lockfile and a configuration file (`pnpm-workspace.yaml`).

```Dockerfile
FROM node:20
Expand Down Expand Up @@ -110,7 +110,7 @@ CMD [ "node", "server.js" ]

It works for both simple and monorepo projects, `--offline` enforces
pnpm not to communicate with the package registry as all needed packages are
already present in the virtual store.
already present in the dependency graph store.

As long as the lockfile is not changed, the build cache is valid up to the
layer, so `RUN pnpm install -r --offline --prod`, will save you much
Expand Down
4 changes: 2 additions & 2 deletions docs/package_json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Additional meta information used for dependencies declared inside `dependencies`

### dependenciesMeta.*.injected

If this is set to `true` for a dependency that is a local workspace package, that package will be installed by creating a hard linked copy in the virtual store (`node_modules/.pnpm`).
If this is set to `true` for a dependency that is a local workspace package, that package will be installed by creating a hard linked copy in the dependency graph store (`node_modules/.pnpm`).

If this is set to `false` or not set, then the dependency will instead be installed by creating a `node_modules` symlink that points to the package's source directory in the workspace. This is the default, as it is faster and ensures that any modifications to the dependency will be immediately visible to its consumers.

Expand All @@ -59,7 +59,7 @@ The `button` dependency will normally be installed by creating a symlink in the

But what if `button` specifies `react` in its `peerDependencies`? If all projects in the monorepo use the same version of `react`, then there is no problem. But what if `button` is required by `card` that uses `react@16` and `form` that uses `react@17`? Normally you'd have to choose a single version of `react` and specify it using `devDependencies` of `button`. Symlinking does not provide a way for the `react` peer dependency to be satisfied differently by different consumers such as `card` and `form`.

The `injected` field solves this problem by installing a hard linked copies of `button` in the virtual store. To accomplish this, the `package.json` of `card` could be configured as follows:
The `injected` field solves this problem by installing a hard linked copies of `button` in the dependency graph store. To accomplish this, the `package.json` of `card` could be configured as follows:

```json
{
Expand Down
24 changes: 12 additions & 12 deletions docs/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ hoistPattern:
* Type: **string[]**

Unlike `hoistPattern`, which hoists dependencies to a hidden modules directory
inside the virtual store, `publicHoistPattern` hoists dependencies matching
inside the dependency graph store, `publicHoistPattern` hoists dependencies matching
the pattern to the root modules directory. Hoisting to the root modules
directory means that application code will have access to phantom dependencies,
even if they modify the resolution strategy improperly.
Expand Down Expand Up @@ -303,7 +303,7 @@ The directory in which dependencies will be installed (instead of

Defines what linker should be used for installing Node packages.

* **isolated** - dependencies are symlinked from a virtual store at `node_modules/.pnpm`.
* **isolated** - dependencies are symlinked from a dependency graph store at `node_modules/.pnpm`.
* **hoisted** - a flat `node_modules` without symlinks is created. Same as the `node_modules` created by npm or Yarn Classic. One of Yarn's libraries is used for hoisting, when this setting is used. Legitimate reasons to use this setting:
1. Your tooling doesn't work well with symlinks. A React Native project will most probably only work if you use a hoisted `node_modules`.
1. Your project is deployed to a serverless hosting provider. Some serverless providers (for instance, AWS Lambda) don't support symlinks. An alternative solution for this problem is to bundle your application before deployment.
Expand All @@ -321,7 +321,7 @@ your linker.
* Default: **true**
* Type: **Boolean**

When `symlink` is set to `false`, pnpm creates a virtual store directory without
When `symlink` is set to `false`, pnpm creates a dependency graph store directory without
any symlinks. It is a useful setting together with `nodeLinker=pnp`.

### enableModulesDir
Expand All @@ -345,15 +345,15 @@ The directory with links to the store. All direct and indirect dependencies of
the project are linked into this directory.

This is a useful setting that can solve issues with long paths on Windows. If
you have some dependencies with very long paths, you can select a virtual store
you have some dependencies with very long paths, you can select a dependency graph store
in the root of your drive (for instance `C:\my-project-store`).

Or you can set the virtual store to `.pnpm` and add it to `.gitignore`. This
Or you can set the dependency graph store to `.pnpm` and add it to `.gitignore`. This
will make stacktraces cleaner as paths to dependencies will be one directory
higher.

**NOTE:** the virtual store cannot be shared between several projects. Every
project should have its own virtual store (except for in workspaces where the
**NOTE:** the dependency graph store cannot be shared between several projects. Every
project should have its own dependency graph store (except for in workspaces where the
root is shared).

### virtualStoreDirMaxLength
Expand All @@ -363,7 +363,7 @@ root is shared).
* On Windows: **60**
* Types: **number**

Sets the maximum allowed length of directory names inside the virtual store directory (`node_modules/.pnpm`). You may set this to a lower number if you encounter long path issues on Windows.
Sets the maximum allowed length of directory names inside the local dependency graph store directory (`node_modules/.pnpm`). You may set this to a lower number if you encounter long path issues on Windows.

### packageImportMethod

Expand Down Expand Up @@ -411,13 +411,13 @@ Added in: v10.12.1
* Type: **Boolean**
* Status: **Experimental**

When enabled, `node_modules` contains only symlinks to a central virtual store, rather than to `node_modules/.pnpm`. By default, this central store is located at `<store-path>/links` (use `pnpm store path` to find `<store-path>`).
When enabled, `node_modules` contains only symlinks to a global dependency graph store, rather than to `node_modules/.pnpm`. By default, this central store is located at `<store-path>/links` (use `pnpm store path` to find `<store-path>`).

In the central virtual store, each package is hard linked into a directory whose name is the hash of its dependency graph. As a result, all projects on the system can symlink their dependencies from this shared location on disk. This approach is conceptually similar to how [NixOS manages packages], using dependency graph hashes to create isolated and shareable package directories in the Nix store.
In the dependency graph store, each package is hard linked into a directory whose name is the hash of its fully resolved dependency graph snapshot. As a result, all projects on the system can symlink their dependencies from this shared location on disk. This approach is conceptually similar to how [NixOS manages packages], using dependency graph hashes to create isolated and shareable package directories in the Nix store.

> This should not be confused with the global content-addressable store. The actual package files are still hard linked from the content-addressable store—but instead of being linked directly into `node_modules/.pnpm`, they are linked into the global virtual store.
> This should not be confused with the global content-addressable store. The actual package files are still hard linked from the content-addressable store—but instead of being linked directly into `node_modules/.pnpm`, they are linked into the global dependency graph store.

Using a global virtual store can significantly speed up installations when a warm cache is available. However, in CI environments (where caches are typically absent), it may slow down installation. If pnpm detects that it is running in CI, this setting is automatically disabled.
Using a global dependency graph store can significantly speed up installations when a warm cache is available. However, in CI environments (where caches are typically absent), it may slow down installation. If pnpm detects that it is running in CI, this setting is automatically disabled.

[NixOS manages packages]: https://nixos.org/guides/how-nix-works/

Expand Down