docs: rename virtual store to dependency graph store

[zkochan]

No description provided.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
pnpm-io	❌ Failed (Inspect)			Jun 28, 2025 0:32am

[zkochan]

If approved, we can add new options with new names and remove the old names in pnpm v11.

[gluxon]

I'm sure there's a bit of context to the rename that I'm not aware of yet. Without that, I think I kind of like the existing "virtual store" name.

It's relatively short and everyone currently knows what it means. While "dependency graph store" might be more accurate, it's longer and less unique.

For example, in macOS, the bottom app bar is called a "Dock". While that's not the perfect name, it's short and everyone is familiar with it. I tend to like short unique names, even if they aren't perfect descriptors. You could imagine an alternate universe where the macOS dock was called "Bottom Application Launcher Bar".

[zkochan]

The virtual store was kind of an internal thing up until now. I don't remember how I came up with this name. I think maybe I borrowed it from Yarn, which has virtual packages.

Now with the global virtual store feature this store will become more complex and I was wondering if the name of this store should more closely reflect the nature of it. Virtual store is very generic while dependency graph store is reflecting what this store contains.

Of course, it can be named anything as long as the docs explain what it does.

[gluxon]

That all makes sense. Appreciate the explanation above. It makes sense that the "global virtual store" is prompting a rename.

Of course, it can be named anything as long as the docs explain what it does.

To suggest one more name, how do you feel about isolated store? I believe the isolated terminology came out of the NPM RFC for Isolated Mode, which you helped on. I know we've since adopted this terminology in several places like our nodeLinker config. I like the idea of node-linker=isolated creating something called the "isolated store".

The current "global virtual store" would then be called "central isolated store". I tend to like the "central" naming over "global" since global has somewhat negative connotation in programming.

Thanks for opening a discussion on this by the way. If that idea above doesn't make sense, feel free to ignore me.

[zkochan]

I think I would rank "central isolated store" the same as "global virtual store". ChatGPT really doesn't like the "central isolated store" name and says it will confuse users as they could think it is per-project and central isolated store is an oxymoron. I am not sure I agree but it did suggest an improved version: hash-isolated graph store (HIGS). HIGS sounds not bad.

[gluxon]

I think I would rank "central isolated store" the same as "global virtual store". ChatGPT really doesn't like the "central isolated store" name and says it will confuse users as they could think it is per-project and central isolated store is an oxymoron.

I could see the point around this name being an oxymoron. To counter a bit though, I think we would rarely refer to it as the "central isolated store". I suspect we would normally call it the "isolated store", and in the case where it matters whether the store is local or shared, we'd refer to the config option: centralize-isolated-store=true.

I am not sure I agree but it did suggest an improved version: hash-isolated graph store (HIGS). HIGS sounds not bad.

Do you know the reasoning for the hash- prefix? I know some paths in node_modules/.pnpm could contain hashes as a workaround for Windows file path limitations. Is that what the hash- part is referencing?

I do still vote to omit the "graph" part since I feel it makes the name longer without adding much meaning?

[zkochan]

When the store is inside a project's node_modules, it is enough to isolate it by <pkgName>@<pkgVersion>_<peersDepGraphHash> because we only allow one package with one set of dependencies in a project (except peer dependencies). But when the store is shared, we need to account for all the combinations of resolved dependencies, so we need to use a directory name that is created by hashing the fully resolved dependency graph of the package. This is documented here: https://pnpm.io/settings#enableglobalvirtualstore

[gluxon]

Gotcha. It makes sense that we'd need to hash the full resolution of a package when the store isn't localized. Appreciate the explanation.

My personal feeling is the hashing is an implementation detail that doesn't necessarily need to be part of the name. The important and coolest part of this store is that it enables the semi-strict node_modules layout, and just the "isolated" part of the name is enough to highlight that.

To clarify, did you want to just call the global variant of the store "hash-isolated graph store"? Would the local variant (e.g. node_modules/.pnpm within a repo) just be "isolated graph store" since there's less hashing happening?

[zkochan]

The local one also uses hashing for the peer dependency graphs, so it probably doesn't make sense to name it differently

[gluxon]

Gotcha. My vote is still leaning isolated store since I think hash is an implementation detail in both the global and local variants, and graph doesn't add much value to the name, but I'm comfortable with you making the final decision. 🙂