feat: allow subspaces to opt out of the PNPM global virtual store

Author: QuanticPotatoes

common/changes/@microsoft/rush/support-pnpm-global-virtual-store_2026-06-11-15-20.json

@@ -2,7 +2,7 @@
   "changes": [
     {
       "packageName": "@microsoft/rush",
-      "comment": "Add PNPM global virtual store support for workspace installs via RUSH_PNPM_ENABLE_GLOBAL_VIRTUAL_STORE.",
+      "comment": "Add PNPM global virtual store support for workspace installs via RUSH_PNPM_ENABLE_GLOBAL_VIRTUAL_STORE, with a per-subspace \"globalVirtualStore\": false opt-out in pnpm-config.json.",
       "type": "minor"
     }
   ],

common/reviews/api/rush-lib.api.md

@@ -1112,6 +1112,7 @@ export interface _IPnpmOptionsJson extends IPackageManagerOptionsJsonBase {
     globalPackageExtensions?: Record<string, IPnpmPackageExtension>;
     globalPatchedDependencies?: Record<string, string>;
     globalPeerDependencyRules?: IPnpmPeerDependencyRules;
+    globalVirtualStore?: boolean;
     // @deprecated (undocumented)
     minimumReleaseAge?: number;
     minimumReleaseAgeExclude?: string[];
@@ -1703,6 +1704,7 @@ export class PnpmOptionsConfiguration extends PackageManagerOptionsConfiguration
     readonly globalPackageExtensions: Record<string, IPnpmPackageExtension> | undefined;
     get globalPatchedDependencies(): Record<string, string> | undefined;
     readonly globalPeerDependencyRules: IPnpmPeerDependencyRules | undefined;
+    readonly globalVirtualStore: boolean | undefined;
     // (undocumented)
     readonly jsonFilename: string | undefined;
     // @internal (undocumented)

libraries/rush-lib/src/api/LastInstallFlag.ts

@@ -7,11 +7,11 @@ import { JsonFile, type JsonObject, Path, type IPackageJson, Objects } from '@ru
 
 import type { PackageManagerName } from './packageManager/PackageManager';
 import type { RushConfiguration } from './RushConfiguration';
-import { EnvironmentConfiguration } from './EnvironmentConfiguration';
 import * as objectUtilities from '../utilities/objectUtilities';
 import type { Subspace } from './Subspace';
 import { Selection } from '../logic/Selection';
 import { FlagFile } from './FlagFile';
+import { isPnpmGlobalVirtualStoreEnabled } from '../logic/pnpm/PnpmGlobalVirtualStore';
 
 const LAST_INSTALL_FLAG_FILE_NAME: string = 'last-install';
 
@@ -218,7 +218,7 @@ export function getCommonTempFlag(
 
   if (currentState.packageManager === 'pnpm' && rushConfiguration.pnpmOptions) {
     currentState.storePath = rushConfiguration.pnpmOptions.pnpmStorePath;
-    if (EnvironmentConfiguration.enablePnpmGlobalVirtualStore) {
+    if (isPnpmGlobalVirtualStoreEnabled(subspace)) {
       currentState.pnpmGlobalVirtualStore = true;
     }
     if (rushConfiguration.pnpmOptions.useWorkspaces) {

libraries/rush-lib/src/logic/installManager/WorkspaceInstallManager.ts

@@ -40,6 +40,7 @@ import { ShrinkwrapFileFactory } from '../ShrinkwrapFileFactory';
 import { BaseProjectShrinkwrapFile } from '../base/BaseProjectShrinkwrapFile';
 import { type CustomTipId, type ICustomTipInfo, PNPM_CUSTOM_TIPS } from '../../api/CustomTipsConfiguration';
 import type { PnpmShrinkwrapFile } from '../pnpm/PnpmShrinkwrapFile';
+import { isPnpmGlobalVirtualStoreEnabled } from '../pnpm/PnpmGlobalVirtualStore';
 import type { Subspace } from '../../api/Subspace';
 import { BaseLinkManager, SymlinkKind } from '../base/BaseLinkManager';
 import { FlagFile } from '../../api/FlagFile';
@@ -506,7 +507,7 @@ export class WorkspaceInstallManager extends BaseInstallManager {
     // Write the common package.json using the "pnpm" field derived above.
     await InstallHelpers.generateCommonPackageJsonAsync(subspace, undefined, pnpmSettings);
 
-    if (EnvironmentConfiguration.enablePnpmGlobalVirtualStore) {
+    if (isPnpmGlobalVirtualStoreEnabled(subspace)) {
       const globalVirtualStoreWarning: string | undefined = validateGlobalVirtualStoreOptions({
         pnpmVersion: this.rushConfiguration.packageManagerToolVersion,
         rushJsonFolder: this.rushConfiguration.rushJsonFolder,
@@ -520,6 +521,9 @@ export class WorkspaceInstallManager extends BaseInstallManager {
         this._terminal.writeWarningLine(globalVirtualStoreWarning);
       }
       workspaceFile.enableGlobalVirtualStore = true;
+    } else {
+      // The workspace file was loaded from disk, so clear a value left by a previous install.
+      workspaceFile.enableGlobalVirtualStore = undefined;
     }
 
     // The pnpm-workspace.yaml settings were already populated by resolvePnpmSettings, and the

libraries/rush-lib/src/logic/pnpm/PnpmGlobalVirtualStore.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { EnvironmentConfiguration } from '../../api/EnvironmentConfiguration';
+import type { Subspace } from '../../api/Subspace';
+
+/**
+ * Whether the PNPM global virtual store applies to this subspace: the environment variable
+ * enables it repo-wide, and a subspace's pnpm-config.json can opt out with `"globalVirtualStore": false`.
+ */
+export function isPnpmGlobalVirtualStoreEnabled(subspace: Subspace): boolean {
+  return (
+    EnvironmentConfiguration.enablePnpmGlobalVirtualStore &&
+    subspace.getPnpmOptions()?.globalVirtualStore !== false
+  );
+}

libraries/rush-lib/src/logic/pnpm/PnpmOptionsConfiguration.ts

@@ -186,6 +186,10 @@ export interface IPnpmOptionsJson extends IPackageManagerOptionsJsonBase {
    * {@inheritDoc PnpmOptionsConfiguration.alwaysInjectDependenciesFromOtherSubspaces}
    */
   alwaysInjectDependenciesFromOtherSubspaces?: boolean;
+  /**
+   * {@inheritDoc PnpmOptionsConfiguration.globalVirtualStore}
+   */
+  globalVirtualStore?: boolean;
   /**
    * {@inheritDoc PnpmOptionsConfiguration.alwaysFullInstall}
    */
@@ -390,6 +394,17 @@ export class PnpmOptionsConfiguration extends PackageManagerOptionsConfiguration
    */
   public readonly alwaysInjectDependenciesFromOtherSubspaces: boolean | undefined;
 
+  /**
+   * Set to `false` to opt this subspace out of PNPM's global virtual store when the
+   * `RUSH_PNPM_ENABLE_GLOBAL_VIRTUAL_STORE` environment variable is enabled.
+   *
+   * @remarks
+   * Useful for subspaces whose tooling cannot follow dependencies outside the subspace's temp folder,
+   * such as a Metro bundler restricted to its `watchFolders`. The default value is undefined, which
+   * follows the environment variable.
+   */
+  public readonly globalVirtualStore: boolean | undefined;
+
   /**
    * The "globalOverrides" setting provides a simple mechanism for overriding version selections
    * for all dependencies of all projects in the monorepo workspace.  The settings are copied
@@ -606,6 +621,7 @@ export class PnpmOptionsConfiguration extends PackageManagerOptionsConfiguration
     this.trustPolicyExclude = json.trustPolicyExclude;
     this.trustPolicyIgnoreAfterMinutes = json.trustPolicyIgnoreAfterMinutes;
     this.alwaysInjectDependenciesFromOtherSubspaces = json.alwaysInjectDependenciesFromOtherSubspaces;
+    this.globalVirtualStore = json.globalVirtualStore;
     this.alwaysFullInstall = json.alwaysFullInstall;
     this.pnpmLockfilePolicies = json.pnpmLockfilePolicies;
     this.globalCatalogs = json.globalCatalogs;

libraries/rush-lib/src/logic/test/WorkspaceInstallManager.test.ts

@@ -1,11 +1,12 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { FileSystem, JsonFile, Path } from '@rushstack/node-core-library';
+import { FileSystem, JsonFile, type JsonObject, Path } from '@rushstack/node-core-library';
 import { StringBufferTerminalProvider, Terminal } from '@rushstack/terminal';
 
 import { EnvironmentConfiguration, EnvironmentVariableNames } from '../../api/EnvironmentConfiguration';
 import { RushConfiguration } from '../../api/RushConfiguration';
+import { getCommonTempFlag, type LastInstallFlag } from '../../api/LastInstallFlag';
 import { RushGlobalFolder } from '../../api/RushGlobalFolder';
 import type { Subspace } from '../../api/Subspace';
 import {
@@ -121,6 +122,7 @@ describe(WorkspaceInstallManager.name, () => {
 
     async function prepareFixtureRepoAsync(options: {
       pnpmStore?: PnpmStoreLocation;
+      globalVirtualStore?: boolean;
     }): Promise<RushConfiguration> {
       const repoPath: string = `${tempFolderPath}/repo`;
       await FileSystem.copyFilesAsync({
@@ -141,12 +143,25 @@ describe(WorkspaceInstallManager.name, () => {
         delete commonPnpmConfigJson.pnpmStore;
       }
       await JsonFile.saveAsync(commonPnpmConfigJson, commonPnpmConfigPath, { updateExistingFile: true });
+      if (options.globalVirtualStore !== undefined) {
+        await JsonFile.saveAsync(
+          { globalVirtualStore: options.globalVirtualStore },
+          `${repoPath}/common/config/subspaces/default/pnpm-config.json`,
+          { ensureFolderExists: true }
+        );
+      }
 
       const rushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(rushJsonPath);
       await FileSystem.ensureFolderAsync(rushConfiguration.defaultSubspace.getSubspaceTempFolderPath());
       return rushConfiguration;
     }
 
+    async function readCommonTempFlagAsync(rushConfiguration: RushConfiguration): Promise<JsonObject> {
+      const flag: LastInstallFlag = getCommonTempFlag(rushConfiguration, rushConfiguration.defaultSubspace);
+      await flag.createAsync();
+      return await JsonFile.loadAsync(flag.path);
+    }
+
     function createInstallManager(rushConfiguration: RushConfiguration): TestWorkspaceInstallManager {
       const terminal: Terminal = new Terminal(new StringBufferTerminalProvider());
       const options: IInstallManagerOptions = {
@@ -190,6 +205,25 @@ describe(WorkspaceInstallManager.name, () => {
       );
       expect(workspaceYaml).toContain('enableGlobalVirtualStore: true');
       expect(Path.convertToSlashes(workspaceYaml)).toContain('../../../a');
+      expect(await readCommonTempFlagAsync(rushConfiguration)).toHaveProperty('pnpmGlobalVirtualStore', true);
+    });
+
+    it('leaves the global virtual store off for a subspace that opts out', async () => {
+      process.env[EnvironmentVariableNames.RUSH_PNPM_ENABLE_GLOBAL_VIRTUAL_STORE] = '1';
+      EnvironmentConfiguration.reset();
+      const rushConfiguration: RushConfiguration = await prepareFixtureRepoAsync({
+        pnpmStore: 'global',
+        globalVirtualStore: false
+      });
+      const installManager: TestWorkspaceInstallManager = createInstallManager(rushConfiguration);
+
+      await installManager.prepareCommonTempForTestAsync(rushConfiguration.defaultSubspace);
+
+      const workspaceYaml: string = await FileSystem.readFileAsync(
+        `${rushConfiguration.defaultSubspace.getSubspaceTempFolderPath()}/pnpm-workspace.yaml`
+      );
+      expect(workspaceYaml).not.toContain('enableGlobalVirtualStore');
+      expect(await readCommonTempFlagAsync(rushConfiguration)).not.toHaveProperty('pnpmGlobalVirtualStore');
     });
 
     it('throws from the workspace install prepare path when using a worktree-local PNPM store', async () => {

libraries/rush-lib/src/schemas/pnpm-config.schema.json

@@ -53,6 +53,11 @@
       "type": "boolean"
     },
 
+    "globalVirtualStore": {
+      "description": "Set to false to opt this subspace out of PNPM's global virtual store when the RUSH_PNPM_ENABLE_GLOBAL_VIRTUAL_STORE environment variable is enabled. Useful for subspaces whose tooling cannot follow dependencies outside the subspace's temp folder, such as a Metro bundler restricted to its watchFolders.\n\nThe default value is undefined, which follows the environment variable.",
+      "type": "boolean"
+    },
+
     "alwaysInjectDependenciesFromOtherSubspaces": {
       "description": "When a project uses `workspace:` to depend on another Rush project, PNPM normally installs it by creating a symlink under `node_modules`.  This generally works well, but in certain cases such as differing `peerDependencies` versions, symlinking may cause trouble such as incorrectly satisfied versions.  For such cases, the dependency can be declared as \"injected\", causing PNPM to copy its built output into `node_modules` like a real install from a registry.  Details here: https://rushjs.io/pages/advanced/injected_deps/\n\nWhen using Rush subspaces, these sorts of versioning problems are much more likely if `workspace:` refers to a project from a different subspace.  This is because the symlink would point to a separate `node_modules` tree installed by a different PNPM lockfile.  A comprehensive solution is to enable `alwaysInjectDependenciesFromOtherSubspaces`, which automatically treats all projects from other subspaces as injected dependencies without having to manually configure them.\n\nNOTE: Use carefully -- excessive file copying can slow down the `rush install` and `pnpm-sync` operations if too many dependencies become injected.\n\nThe default value is false.",
       "type": "boolean"