[{"data":1,"prerenderedAt":669},["ShallowReactive",2],{"docs-page:\u002Fdocs\u002Fpackage-manager\u002Fglobal-virtual-store":3,"docs-pages":323},{"id":4,"title":5,"body":6,"description":16,"extension":316,"meta":317,"navigation":318,"path":319,"seo":320,"stem":321,"__hash__":322},"docs\u002Fdocs\u002Fpackage-manager\u002Fglobal-virtual-store.md","Global virtual store",{"type":7,"value":8,"toc":307},"minimark",[9,13,17,20,55,60,67,77,81,84,90,93,97,104,107,111,121,125,128,148,154,158,165,179,182,191,194,212,216,226,229,256,259,268,277,280,288,291,300,303],[10,11,5],"h1",{"id":12},"global-virtual-store",[14,15,16],"p",{},"scpm's global virtual store reuses fully materialized package directories across\nprojects. It is enabled by default for local installs and disabled under CI.",[14,18,19],{},"This is separate from the global content store:",[21,22,23,37],"ul",{},[24,25,26,27,31,32,36],"li",{},"The ",[28,29,30],"strong",{},"global content store"," (",[33,34,35],"code",{},"$XDG_DATA_HOME\u002Fscpm\u002Fstore\u002Fv1\u002F",") stores\npackage files by BLAKE3 hash. Every install uses it.",[24,38,26,39,42,43,46,47,50,51,54],{},[28,40,41],{},"global virtual store","\n(",[33,44,45],{},"$XDG_CACHE_HOME\u002Fscpm\u002Fvirtual-store\u002F",", defaulting to\n",[33,48,49],{},"~\u002F.cache\u002Fscpm\u002Fvirtual-store\u002F",") stores package directory trees keyed by\ndependency graph. Project ",[33,52,53],{},"node_modules"," entries symlink into it.",[56,57,59],"h2",{"id":58},"default-behavior","Default behavior",[14,61,62,63,66],{},"Without the global virtual store, each project gets its own virtual store under\n",[33,64,65],{},"node_modules\u002F.scpm\u002F",". Package files are still deduplicated through the global\ncontent store, but the directory tree is rebuilt for each checkout.",[68,69,75],"pre",{"className":70,"code":72,"language":73,"meta":74},[71],"language-text","project-a\u002F\n  node_modules\u002F\n    react -> .scpm\u002Freact@18.2.0\u002Fnode_modules\u002Freact\n    .scpm\u002F\n      react@18.2.0\u002F\n        node_modules\u002F\n          react\u002F       # files imported from the content store\n\nproject-b\u002F\n  node_modules\u002F\n    react -> .scpm\u002Freact@18.2.0\u002Fnode_modules\u002Freact\n    .scpm\u002F\n      react@18.2.0\u002F\n        node_modules\u002F\n          react\u002F       # same file content, separate directory tree\n","text","",[33,76,72],{"__ignoreMap":74},[56,78,80],{"id":79},"with-the-global-virtual-store","With the global virtual store",[14,82,83],{},"With the global virtual store enabled, scpm builds the package tree once in the\nshared cache. Each project points directly at that shared tree:",[68,85,88],{"className":86,"code":87,"language":73,"meta":74},[71],"project-a\u002F\n  node_modules\u002F\n    react -> $XDG_CACHE_HOME\u002Fscpm\u002Fvirtual-store\u002Freact@18.2.0\u002F\u003Cgraph-hash>\u002Fnode_modules\u002Freact\n\nproject-b\u002F\n  node_modules\u002F\n    react -> $XDG_CACHE_HOME\u002Fscpm\u002Fvirtual-store\u002Freact@18.2.0\u002F\u003Cgraph-hash>\u002Fnode_modules\u002Freact\n",[33,89,87],{"__ignoreMap":74},[14,91,92],{},"The global virtual store still imports package files from the global content\nstore. The win is that scpm avoids rebuilding the same package directory tree in\nevery checkout.",[56,94,96],{"id":95},"package-identity","Package identity",[14,98,99,100,103],{},"Entries are keyed by the resolved dependency graph, not just by package name and\nversion. Two projects can share ",[33,101,102],{},"react@18.2.0"," when the surrounding dependency\ngraph matches. If peer dependencies or transitive dependencies differ, scpm\ncreates a separate entry with a different graph hash.",[14,105,106],{},"That keeps Node's resolution semantics intact: sharing only happens when the\nmaterialized package tree is safe to reuse.",[56,108,110],{"id":109},"compared-with-pnpm","Compared with pnpm",[14,112,113,114,120],{},"pnpm has a similar\n",[115,116,41],"a",{"href":117,"rel":118},"https:\u002F\u002Fpnpm.io\u002Fglobal-virtual-store",[119],"nofollow",", but project\ninstalls leave it disabled by default. scpm enables the global virtual store by\ndefault for local installs, then turns it off automatically under CI and for\nknown symlink-sensitive toolchains.",[56,122,124],{"id":123},"when-it-helps","When it helps",[14,126,127],{},"The global virtual store is most useful on developer machines:",[21,129,130,133,138,141],{},[24,131,132],{},"multiple worktrees or checkouts of the same repo",[24,134,135,136],{},"repeated fresh installs after deleting ",[33,137,53],{},[24,139,140],{},"several projects using the same package versions",[24,142,143,144,147],{},"one-off ",[33,145,146],{},"scpmx"," and script workflows that benefit from warm local state",[14,149,150,151,153],{},"It is usually less useful in CI. CI jobs often start without a warm\n",[33,152,45],{},", so scpm disables the global virtual store\nunder CI and materializes packages per project instead.",[56,155,157],{"id":156},"configuration","Configuration",[14,159,160,161,164],{},"Set the project default in ",[33,162,163],{},".npmrc",":",[68,166,170],{"className":167,"code":168,"language":169,"meta":74,"style":74},"language-ini shiki shiki-themes github-light github-dark","enableGlobalVirtualStore=true\n","ini",[33,171,172],{"__ignoreMap":74},[173,174,177],"span",{"class":175,"line":176},"line",1,[173,178,168],{},[14,180,181],{},"or:",[68,183,185],{"className":167,"code":184,"language":169,"meta":74,"style":74},"enableGlobalVirtualStore=false\n",[33,186,187],{"__ignoreMap":74},[173,188,189],{"class":175,"line":176},[173,190,184],{},[14,192,193],{},"Override a single command with:",[68,195,199],{"className":196,"code":197,"language":198,"meta":74,"style":74},"language-sh shiki shiki-themes github-light github-dark","scpm install --enable-global-virtual-store\nscpm install --disable-global-virtual-store\n","sh",[33,200,201,206],{"__ignoreMap":74},[173,202,203],{"class":175,"line":176},[173,204,205],{},"scpm install --enable-global-virtual-store\n",[173,207,209],{"class":175,"line":208},2,[173,210,211],{},"scpm install --disable-global-virtual-store\n",[56,213,215],{"id":214},"limitations","Limitations",[14,217,218,219,222,223,225],{},"Some tools canonicalize ",[33,220,221],{},"node_modules\u002F\u003Cpkg>"," symlinks to their real path and\nthen walk upward looking for project files, app roots, or hoisted dependencies.\nWhen the real path is in ",[33,224,45],{},", that walk has\nescaped the project and the tool can fail.",[14,227,228],{},"scpm automatically falls back to per-project materialization when an importer\ndepends on a package with a known global-virtual-store incompatibility. The\ndefault trigger list is:",[21,230,231,236,241,246,251],{},[24,232,233],{},[33,234,235],{},"next",[24,237,238],{},[33,239,240],{},"nuxt",[24,242,243],{},[33,244,245],{},"vite",[24,247,248],{},[33,249,250],{},"vitepress",[24,252,253],{},[33,254,255],{},"parcel",[14,257,258],{},"When that happens, install still succeeds and scpm prints a warning. Repeat\ninstalls of that project just won't share materialized package directories\nacross projects.",[14,260,261,262,265,266,164],{},"To add a package to the trigger list, append entries to\n",[33,263,264],{},"disableGlobalVirtualStoreForPackages"," in ",[33,267,163],{},[68,269,271],{"className":167,"code":270,"language":169,"meta":74,"style":74},"disableGlobalVirtualStoreForPackages[]=my-tool\n",[33,272,273],{"__ignoreMap":74},[173,274,275],{"class":175,"line":176},[173,276,270],{},[14,278,279],{},"To silence the warning while keeping the fallback, set:",[68,281,282],{"className":167,"code":184,"language":169,"meta":74,"style":74},[33,283,284],{"__ignoreMap":74},[173,285,286],{"class":175,"line":176},[173,287,184],{},[14,289,290],{},"To opt out of the compatibility heuristic entirely, set:",[68,292,294],{"className":167,"code":293,"language":169,"meta":74,"style":74},"disableGlobalVirtualStoreForPackages=[]\n",[33,295,296],{"__ignoreMap":74},[173,297,298],{"class":175,"line":176},[173,299,293],{},[14,301,302],{},"Only use that when you know the project's tools tolerate symlinks that point\noutside the project.",[304,305,306],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":74,"searchDepth":208,"depth":208,"links":308},[309,310,311,312,313,314,315],{"id":58,"depth":208,"text":59},{"id":79,"depth":208,"text":80},{"id":95,"depth":208,"text":96},{"id":109,"depth":208,"text":110},{"id":123,"depth":208,"text":124},{"id":156,"depth":208,"text":157},{"id":214,"depth":208,"text":215},"md",{},true,"\u002Fdocs\u002Fpackage-manager\u002Fglobal-virtual-store",{"title":5,"description":16},"docs\u002Fpackage-manager\u002Fglobal-virtual-store","RSrsWs_YUYQkr-f06c_ekWbk0KWyOPX3W4tkVa5pIUI",[324,327,330,333,336,339,342,345,348,351,354,357,360,363,366,369,372,375,378,381,384,387,390,393,396,399,402,405,408,411,414,417,420,423,426,429,432,435,438,441,444,447,450,453,456,459,462,465,468,471,474,477,480,483,486,489,492,495,498,501,504,507,510,513,516,519,522,525,528,531,534,537,540,543,546,549,552,555,558,561,564,567,570,573,576,579,582,585,588,591,594,597,600,603,606,608,611,612,615,618,621,624,627,630,633,636,639,642,645,648,651,654,657,660,663,666],{"path":325,"title":326},"\u002Fdocs\u002Fbenchmarks","Benchmarks",{"path":328,"title":329},"\u002Fdocs\u002Fbun-users","For bun users",{"path":331,"title":332},"\u002Fdocs\u002Fcli\u002Fadd","scpm add",{"path":334,"title":335},"\u002Fdocs\u002Fcli\u002Fapprove-builds","scpm approve-builds",{"path":337,"title":338},"\u002Fdocs\u002Fcli\u002Faudit","scpm audit",{"path":340,"title":341},"\u002Fdocs\u002Fcli\u002Fbin","scpm bin",{"path":343,"title":344},"\u002Fdocs\u002Fcli\u002Fcache","scpm cache",{"path":346,"title":347},"\u002Fdocs\u002Fcli\u002Fcache\u002Fdelete","scpm cache delete",{"path":349,"title":350},"\u002Fdocs\u002Fcli\u002Fcache\u002Flist","scpm cache list",{"path":352,"title":353},"\u002Fdocs\u002Fcli\u002Fcache\u002Flist-registries","scpm cache list-registries",{"path":355,"title":356},"\u002Fdocs\u002Fcli\u002Fcache\u002Fprune","scpm cache prune",{"path":358,"title":359},"\u002Fdocs\u002Fcli\u002Fcache\u002Fview","scpm cache view",{"path":361,"title":362},"\u002Fdocs\u002Fcli\u002Fcat-file","scpm cat-file",{"path":364,"title":365},"\u002Fdocs\u002Fcli\u002Fcat-index","scpm cat-index",{"path":367,"title":368},"\u002Fdocs\u002Fcli\u002Fcheck","scpm check",{"path":370,"title":371},"\u002Fdocs\u002Fcli\u002Fci","scpm ci",{"path":373,"title":374},"\u002Fdocs\u002Fcli\u002Fclean","scpm clean",{"path":376,"title":377},"\u002Fdocs\u002Fcli\u002Fcompletion","scpm completion",{"path":379,"title":380},"\u002Fdocs\u002Fcli\u002Fconfig","scpm config",{"path":382,"title":383},"\u002Fdocs\u002Fcli\u002Fconfig\u002Fdelete","scpm config delete",{"path":385,"title":386},"\u002Fdocs\u002Fcli\u002Fconfig\u002Fexplain","scpm config explain",{"path":388,"title":389},"\u002Fdocs\u002Fcli\u002Fconfig\u002Ffind","scpm config find",{"path":391,"title":392},"\u002Fdocs\u002Fcli\u002Fconfig\u002Fget","scpm config get",{"path":394,"title":395},"\u002Fdocs\u002Fcli\u002Fconfig\u002Flist","scpm config list",{"path":397,"title":398},"\u002Fdocs\u002Fcli\u002Fconfig\u002Fset","scpm config set",{"path":400,"title":401},"\u002Fdocs\u002Fcli\u002Fconfig\u002Ftui","scpm config tui",{"path":403,"title":404},"\u002Fdocs\u002Fcli\u002Fcreate","scpm create",{"path":406,"title":407},"\u002Fdocs\u002Fcli\u002Fdedupe","scpm dedupe",{"path":409,"title":410},"\u002Fdocs\u002Fcli\u002Fdeploy","scpm deploy",{"path":412,"title":413},"\u002Fdocs\u002Fcli\u002Fdeprecate","scpm deprecate",{"path":415,"title":416},"\u002Fdocs\u002Fcli\u002Fdeprecations","scpm deprecations",{"path":418,"title":419},"\u002Fdocs\u002Fcli\u002Fdiag","scpm diag",{"path":421,"title":422},"\u002Fdocs\u002Fcli\u002Fdiag\u002Fanalyze","scpm diag analyze",{"path":424,"title":425},"\u002Fdocs\u002Fcli\u002Fdiag\u002Fcompare","scpm diag compare",{"path":427,"title":428},"\u002Fdocs\u002Fcli\u002Fdist-tag","scpm dist-tag",{"path":430,"title":431},"\u002Fdocs\u002Fcli\u002Fdist-tag\u002Fadd","scpm dist-tag add",{"path":433,"title":434},"\u002Fdocs\u002Fcli\u002Fdist-tag\u002Fls","scpm dist-tag ls",{"path":436,"title":437},"\u002Fdocs\u002Fcli\u002Fdist-tag\u002Frm","scpm dist-tag rm",{"path":439,"title":440},"\u002Fdocs\u002Fcli\u002Fdlx","scpm dlx",{"path":442,"title":443},"\u002Fdocs\u002Fcli\u002Fdoctor","scpm doctor",{"path":445,"title":446},"\u002Fdocs\u002Fcli\u002Fexec","scpm exec",{"path":448,"title":449},"\u002Fdocs\u002Fcli\u002Ffetch","scpm fetch",{"path":451,"title":452},"\u002Fdocs\u002Fcli\u002Ffind-hash","scpm find-hash",{"path":454,"title":455},"\u002Fdocs\u002Fcli\u002Fignored-builds","scpm ignored-builds",{"path":457,"title":458},"\u002Fdocs\u002Fcli\u002Fimport","scpm import",{"path":460,"title":461},"\u002Fdocs\u002Fcli","scpm",{"path":463,"title":464},"\u002Fdocs\u002Fcli\u002Finit","scpm init",{"path":466,"title":467},"\u002Fdocs\u002Fcli\u002Finstall","scpm install",{"path":469,"title":470},"\u002Fdocs\u002Fcli\u002Flicenses","scpm licenses",{"path":472,"title":473},"\u002Fdocs\u002Fcli\u002Flink","scpm link",{"path":475,"title":476},"\u002Fdocs\u002Fcli\u002Flist","scpm list",{"path":478,"title":479},"\u002Fdocs\u002Fcli\u002Flogin","scpm login",{"path":481,"title":482},"\u002Fdocs\u002Fcli\u002Flogout","scpm logout",{"path":484,"title":485},"\u002Fdocs\u002Fcli\u002Foutdated","scpm outdated",{"path":487,"title":488},"\u002Fdocs\u002Fcli\u002Fpack","scpm pack",{"path":490,"title":491},"\u002Fdocs\u002Fcli\u002Fpatch","scpm patch",{"path":493,"title":494},"\u002Fdocs\u002Fcli\u002Fpatch-commit","scpm patch-commit",{"path":496,"title":497},"\u002Fdocs\u002Fcli\u002Fpatch-remove","scpm patch-remove",{"path":499,"title":500},"\u002Fdocs\u002Fcli\u002Fpeers","scpm peers",{"path":502,"title":503},"\u002Fdocs\u002Fcli\u002Fpeers\u002Fcheck","scpm peers check",{"path":505,"title":506},"\u002Fdocs\u002Fcli\u002Fprune","scpm prune",{"path":508,"title":509},"\u002Fdocs\u002Fcli\u002Fpublish","scpm publish",{"path":511,"title":512},"\u002Fdocs\u002Fcli\u002Fpurge","scpm purge",{"path":514,"title":515},"\u002Fdocs\u002Fcli\u002Fquery","scpm query",{"path":517,"title":518},"\u002Fdocs\u002Fcli\u002Frebuild","scpm rebuild",{"path":520,"title":521},"\u002Fdocs\u002Fcli\u002Frecursive","scpm recursive",{"path":523,"title":524},"\u002Fdocs\u002Fcli\u002Fremove","scpm remove",{"path":526,"title":527},"\u002Fdocs\u002Fcli\u002Frestart","scpm restart",{"path":529,"title":530},"\u002Fdocs\u002Fcli\u002Froot","scpm root",{"path":532,"title":533},"\u002Fdocs\u002Fcli\u002Frun","scpm run",{"path":535,"title":536},"\u002Fdocs\u002Fcli\u002Fsbom","scpm sbom",{"path":538,"title":539},"\u002Fdocs\u002Fcli\u002Fsponsors","scpm sponsors",{"path":541,"title":542},"\u002Fdocs\u002Fcli\u002Fstage","scpm stage",{"path":544,"title":545},"\u002Fdocs\u002Fcli\u002Fstart","scpm start",{"path":547,"title":548},"\u002Fdocs\u002Fcli\u002Fstop","scpm stop",{"path":550,"title":551},"\u002Fdocs\u002Fcli\u002Fstore","scpm store",{"path":553,"title":554},"\u002Fdocs\u002Fcli\u002Fstore\u002Fadd","scpm store add",{"path":556,"title":557},"\u002Fdocs\u002Fcli\u002Fstore\u002Fpath","scpm store path",{"path":559,"title":560},"\u002Fdocs\u002Fcli\u002Fstore\u002Fprune","scpm store prune",{"path":562,"title":563},"\u002Fdocs\u002Fcli\u002Fstore\u002Fstatus","scpm store status",{"path":565,"title":566},"\u002Fdocs\u002Fcli\u002Ftest","scpm test",{"path":568,"title":569},"\u002Fdocs\u002Fcli\u002Fundeprecate","scpm undeprecate",{"path":571,"title":572},"\u002Fdocs\u002Fcli\u002Funlink","scpm unlink",{"path":574,"title":575},"\u002Fdocs\u002Fcli\u002Funpublish","scpm unpublish",{"path":577,"title":578},"\u002Fdocs\u002Fcli\u002Fupdate","scpm update",{"path":580,"title":581},"\u002Fdocs\u002Fcli\u002Fversion","scpm version",{"path":583,"title":584},"\u002Fdocs\u002Fcli\u002Fview","scpm view",{"path":586,"title":587},"\u002Fdocs\u002Fcli\u002Fwhy","scpm why",{"path":589,"title":590},"\u002Fdocs\u002Ferror-codes","Error and warning codes",{"path":592,"title":593},"\u002Fdocs\u002Fgetting-started","Getting Started",{"path":595,"title":596},"\u002Fdocs\u002Fguide","Guide",{"path":598,"title":599},"\u002Fdocs","SCPM Documentation",{"path":601,"title":602},"\u002Fdocs\u002Finstallation","Installation",{"path":604,"title":605},"\u002Fdocs\u002Fnpm-users","For npm users",{"path":607,"title":157},"\u002Fdocs\u002Fpackage-manager\u002Fconfiguration",{"path":609,"title":610},"\u002Fdocs\u002Fpackage-manager\u002Fdependencies","Manage dependencies",{"path":319,"title":5},{"path":613,"title":614},"\u002Fdocs\u002Fpackage-manager\u002Finstall","Install dependencies",{"path":616,"title":617},"\u002Fdocs\u002Fpackage-manager\u002Fjailed-builds","Jailed dependency builds",{"path":619,"title":620},"\u002Fdocs\u002Fpackage-manager\u002Flifecycle-scripts","Lifecycle scripts",{"path":622,"title":623},"\u002Fdocs\u002Fpackage-manager\u002Flockfiles","Lockfiles",{"path":625,"title":626},"\u002Fdocs\u002Fpackage-manager\u002Fnode-modules","node_modules layout",{"path":628,"title":629},"\u002Fdocs\u002Fpackage-manager\u002Fpublishing","Publishing",{"path":631,"title":632},"\u002Fdocs\u002Fpackage-manager\u002Fregistry-auth","Registry and auth",{"path":634,"title":635},"\u002Fdocs\u002Fpackage-manager\u002Fscripts","Run scripts and binaries",{"path":637,"title":638},"\u002Fdocs\u002Fpackage-manager\u002Fsecurity-scanner","Security scanner",{"path":640,"title":641},"\u002Fdocs\u002Fpackage-manager\u002Fworkspaces","Workspaces",{"path":643,"title":644},"\u002Fdocs\u002Fpnpm-users","For pnpm users",{"path":646,"title":647},"\u002Fdocs\u002Fsecurity","Security",{"path":649,"title":650},"\u002Fdocs\u002Fsettings\u002Fcli","CLI Settings",{"path":652,"title":653},"\u002Fdocs\u002Fsettings\u002Fenv","Environment Settings",{"path":655,"title":656},"\u002Fdocs\u002Fsettings","Settings",{"path":658,"title":659},"\u002Fdocs\u002Fsettings\u002Fnpmrc",".npmrc Settings",{"path":661,"title":662},"\u002Fdocs\u002Fsettings\u002Fworkspace-yaml","Workspace YAML Settings",{"path":664,"title":665},"\u002Fdocs\u002Ftroubleshooting","Troubleshooting",{"path":667,"title":668},"\u002Fdocs\u002Fyarn-users","For yarn users",1780584396925]