feat: support pnpm global virtual store settings

Author: EscapeB

build-tests/rush-package-manager-integration-test/README.md

@@ -1,6 +1,6 @@
 # Rush Package Manager Integration Tests
 
-This directory contains integration tests for verifying Rush works correctly with different package managers after the tar 7.x upgrade.
+This directory contains integration tests for verifying Rush works correctly with different package managers.
 
 ## Background
 
@@ -10,6 +10,8 @@ Rush's npm and yarn modes use temp project tarballs (stored in `common/temp/proj
 
 These tests ensure the tar 7.x upgrade works correctly with these workflows.
 
+The PNPM test additionally verifies Rush's workspace install integration with PNPM's global virtual store.
+
 ## Tests
 
 The test suite is written in TypeScript using `@rushstack/node-core-library` for cross-platform compatibility.
@@ -30,6 +32,14 @@ Tests Rush yarn mode by:
 - Running `rush install`
 - Running `rush build` (verifies everything works end-to-end)
 
+### testPnpmGlobalVirtualStore.ts
+Tests Rush pnpm workspace mode with global virtual store by:
+- Initializing a Rush repo with `pnpmVersion` configured
+- Enabling `useWorkspaces` and `enableGlobalVirtualStore`
+- Running `rush update`
+- Running `rush install`
+- Verifying the generated workspace file, shared PNPM store, dependency links, and build output
+
 ## Prerequisites
 
 Before running these tests:
@@ -62,6 +72,7 @@ These integration tests verify:
 - ✓ Tarballs are extracted correctly during `rush install`
 - ✓ File permissions are preserved (tar filter function works)
 - ✓ Dependencies are linked properly between projects
+- ✓ PNPM global virtual store is passed through to a real workspace install
 - ✓ The complete workflow (update → install → build) succeeds
 - ✓ Built code executes correctly
 
@@ -70,6 +81,7 @@ These integration tests verify:
 Each test creates a temporary Rush repository in `/tmp/rush-package-manager-test/`:
 - `/tmp/rush-package-manager-test/npm-test-repo/` - npm mode test repository
 - `/tmp/rush-package-manager-test/yarn-test-repo/` - yarn mode test repository
+- `/tmp/rush-package-manager-test/pnpm-global-virtual-store-test-repo/` - pnpm global virtual store test repository
 
 These directories are cleaned up at the start of each test run.
 
@@ -86,6 +98,7 @@ The tests use:
 The tar library is used in:
 - `libraries/rush-lib/src/logic/TempProjectHelper.ts` - Creates tarballs
 - `libraries/rush-lib/src/logic/npm/NpmLinkManager.ts` - Extracts tarballs
+- `libraries/rush-lib/src/logic/installManager/WorkspaceInstallManager.ts` - Generates PNPM workspace files
 
 ## Troubleshooting
 

build-tests/rush-package-manager-integration-test/package.json

@@ -2,7 +2,7 @@
   "name": "rush-package-manager-integration-test",
   "version": "1.0.0",
   "private": true,
-  "description": "Integration tests for non-pnpm package managers in Rush.",
+  "description": "Integration tests for package managers in Rush.",
   "license": "MIT",
   "scripts": {
     "_phase:build": "heft build --clean",

build-tests/rush-package-manager-integration-test/src/TestHelper.ts

@@ -4,7 +4,7 @@
 import * as path from 'node:path';
 import type * as child_process from 'node:child_process';
 
-import { FileSystem, Executable, JsonFile, type JsonObject } from '@rushstack/node-core-library';
+import { FileSystem, Executable, JsonFile, Path, type JsonObject } from '@rushstack/node-core-library';
 import type { ITerminal } from '@rushstack/terminal';
 
 /**
@@ -23,14 +23,19 @@ export class TestHelper {
   /**
    * Execute a Rush command using the locally-built Rush
    */
-  public async executeRushAsync(args: string[], workingDirectory: string): Promise<void> {
+  public async executeRushAsync(
+    args: string[],
+    workingDirectory: string,
+    environment?: NodeJS.ProcessEnv
+  ): Promise<void> {
     this._terminal.writeLine(`Executing: ${process.argv0} ${this._rushBinPath} ${args.join(' ')}`);
 
     const childProcess: child_process.ChildProcess = Executable.spawn(
       process.argv0,
       [this._rushBinPath, ...args],
       {
         currentWorkingDirectory: workingDirectory,
+        environment,
         stdio: 'inherit'
       }
     );
@@ -45,7 +50,7 @@ export class TestHelper {
    */
   public async createTestRepoAsync(
     testRepoPath: string,
-    packageManagerType: 'npm' | 'yarn',
+    packageManagerType: 'npm' | 'pnpm' | 'yarn',
     packageManagerVersion: string
   ): Promise<void> {
     // Clean up previous test run and create empty test repo directory
@@ -66,6 +71,10 @@ export class TestHelper {
       delete rushJson.pnpmVersion;
       delete rushJson.yarnVersion;
       rushJson.npmVersion = packageManagerVersion;
+    } else if (packageManagerType === 'pnpm') {
+      delete rushJson.npmVersion;
+      delete rushJson.yarnVersion;
+      rushJson.pnpmVersion = packageManagerVersion;
     } else if (packageManagerType === 'yarn') {
       delete rushJson.pnpmVersion;
       delete rushJson.npmVersion;
@@ -151,7 +160,9 @@ export class TestHelper {
       // Verify symlinks resolve correctly for local dependencies
       if (dep.startsWith('test-project-')) {
         const depRealPath: string = await FileSystem.getRealPathAsync(depPath);
-        const expectedRealPath: string = path.join(testRepoPath, 'projects', dep);
+        const expectedRealPath: string = await FileSystem.getRealPathAsync(
+          path.join(testRepoPath, 'projects', dep)
+        );
         if (depRealPath !== expectedRealPath) {
           throw new Error(
             `ERROR: Symlink for ${dep} does not resolve correctly!\n` +
@@ -164,6 +175,75 @@ export class TestHelper {
     this._terminal.writeLine('✓ Dependencies installed correctly');
   }
 
+  /**
+   * Verify that PNPM's global virtual store was enabled and moved out of the workspace node_modules folder.
+   */
+  public async verifyPnpmGlobalVirtualStoreAsync(
+    testRepoPath: string,
+    sharedStorePath: string,
+    externalDependencyPaths: string[]
+  ): Promise<void> {
+    this._terminal.writeLine('\nVerifying PNPM global virtual store structure...');
+
+    const workspaceFilePath: string = path.join(testRepoPath, 'common/temp/pnpm-workspace.yaml');
+    const workspaceFileContents: string = await FileSystem.readFileAsync(workspaceFilePath);
+    if (!workspaceFileContents.includes('enableGlobalVirtualStore: true')) {
+      throw new Error(`ERROR: enableGlobalVirtualStore was not written to ${workspaceFilePath}`);
+    }
+
+    const localVirtualStorePath: string = path.join(testRepoPath, 'common/temp/node_modules/.pnpm');
+    if (await FileSystem.existsAsync(localVirtualStorePath)) {
+      const localVirtualStoreItemNames: string[] =
+        await FileSystem.readFolderItemNamesAsync(localVirtualStorePath);
+      const unexpectedLocalPackageFolders: string[] = localVirtualStoreItemNames.filter(
+        (itemName) => itemName !== 'lock.yaml' && itemName !== 'node_modules'
+      );
+      if (unexpectedLocalPackageFolders.length > 0) {
+        throw new Error(
+          `ERROR: Expected ${localVirtualStorePath} to omit package instance folders, but found: ` +
+            unexpectedLocalPackageFolders.join(', ')
+        );
+      }
+    }
+
+    if (!(await FileSystem.existsAsync(sharedStorePath))) {
+      throw new Error(`ERROR: Shared PNPM store was not created at ${sharedStorePath}`);
+    }
+
+    const sharedStoreItemNames: string[] = await FileSystem.readFolderItemNamesAsync(sharedStorePath);
+    if (sharedStoreItemNames.length === 0) {
+      throw new Error(`ERROR: Shared PNPM store is empty at ${sharedStorePath}`);
+    }
+
+    const sharedStoreRealPath: string = await FileSystem.getRealPathAsync(sharedStorePath);
+    const localVirtualStoreRealPath: string | undefined = (await FileSystem.existsAsync(
+      localVirtualStorePath
+    ))
+      ? await FileSystem.getRealPathAsync(localVirtualStorePath)
+      : undefined;
+    for (const externalDependencyPath of externalDependencyPaths) {
+      const dependencyPath: string = path.join(testRepoPath, externalDependencyPath);
+      const dependencyRealPath: string = await FileSystem.getRealPathAsync(dependencyPath);
+      if (!Path.isUnderOrEqual(dependencyRealPath, sharedStoreRealPath)) {
+        throw new Error(
+          `ERROR: Expected ${dependencyPath} to resolve under the shared PNPM store.\n` +
+            `Shared store: ${sharedStoreRealPath}\n` +
+            `Actual: ${dependencyRealPath}`
+        );
+      }
+
+      if (localVirtualStoreRealPath && Path.isUnderOrEqual(dependencyRealPath, localVirtualStoreRealPath)) {
+        throw new Error(
+          `ERROR: Expected ${dependencyPath} to resolve outside the local virtual store.\n` +
+            `Local virtual store: ${localVirtualStoreRealPath}\n` +
+            `Actual: ${dependencyRealPath}`
+        );
+      }
+    }
+
+    this._terminal.writeLine('✓ PNPM global virtual store structure verified');
+  }
+
   /**
    * Verify that build outputs were created
    */

build-tests/rush-package-manager-integration-test/src/runTests.ts

@@ -4,6 +4,7 @@
 import { Terminal, ConsoleTerminalProvider } from '@rushstack/terminal';
 
 import { testNpmModeAsync } from './testNpmMode';
+import { testPnpmGlobalVirtualStoreAsync } from './testPnpmGlobalVirtualStore';
 import { testYarnModeAsync } from './testYarnMode';
 
 /**
@@ -17,7 +18,7 @@ async function runTestsAsync(): Promise<void> {
   terminal.writeLine('==========================================');
   terminal.writeLine('');
   terminal.writeLine('These tests verify that the tar 7.x upgrade works correctly');
-  terminal.writeLine('with different Rush package managers (npm, yarn).');
+  terminal.writeLine('with different Rush package managers (npm, pnpm, yarn).');
   terminal.writeLine('');
   terminal.writeLine('Tests will:');
   terminal.writeLine('  1. Create Rush repos using locally-built Rush');
@@ -45,6 +46,20 @@ async function runTestsAsync(): Promise<void> {
     terminal.writeErrorLine(String(error));
   }
 
+  // Run pnpm global virtual store test
+  terminal.writeLine('==========================================');
+  terminal.writeLine('Running PNPM global virtual store test...');
+  terminal.writeLine('==========================================');
+  try {
+    await testPnpmGlobalVirtualStoreAsync(terminal);
+    testsPassed++;
+  } catch (error) {
+    testsFailed++;
+    failedTests.push('PNPM global virtual store');
+    terminal.writeErrorLine('⚠️  PNPM global virtual store test FAILED');
+    terminal.writeErrorLine(String(error));
+  }
+
   // Run yarn mode test
   terminal.writeLine('==========================================');
   terminal.writeLine('Running Yarn mode test...');
@@ -81,6 +96,7 @@ async function runTestsAsync(): Promise<void> {
     terminal.writeLine('');
     terminal.writeLine('The tar 7.x upgrade is working correctly with:');
     terminal.writeLine('  - NPM package manager');
+    terminal.writeLine('  - PNPM global virtual store');
     terminal.writeLine('  - Yarn package manager');
     terminal.writeLine('');
     process.exit(0);

build-tests/rush-package-manager-integration-test/src/testPnpmGlobalVirtualStore.ts

@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { FileSystem, JsonFile, type JsonObject } from '@rushstack/node-core-library';
+import type { ITerminal } from '@rushstack/terminal';
+
+import { TestHelper } from './TestHelper';
+
+/**
+ * Integration test for Rush PNPM workspace mode with PNPM's global virtual store.
+ * This test verifies that Rush passes enableGlobalVirtualStore through to a real PNPM install.
+ */
+export async function testPnpmGlobalVirtualStoreAsync(terminal: ITerminal): Promise<void> {
+  const helper: TestHelper = new TestHelper(terminal);
+  // Use system temp directory to avoid rush init detecting parent rush.json
+  const testRepoPath: string = path.join(
+    os.tmpdir(),
+    'rush-package-manager-test',
+    'pnpm-global-virtual-store-test-repo'
+  );
+  const sharedStorePath: string = path.join(os.tmpdir(), 'rush-package-manager-test', 'shared-pnpm-store');
+  const rushEnvironment: NodeJS.ProcessEnv = {
+    ...process.env,
+    CI: 'false',
+    PNPM_CONFIG_CI: 'false',
+    RUSH_PNPM_STORE_PATH: sharedStorePath
+  };
+
+  terminal.writeLine('==========================================');
+  terminal.writeLine('Rush PNPM Global Virtual Store Integration Test');
+  terminal.writeLine('==========================================');
+  terminal.writeLine('');
+  terminal.writeLine(
+    'This test verifies that Rush can enable PNPM global virtual store during workspace installs.'
+  );
+  terminal.writeLine('');
+
+  await helper.createTestRepoAsync(testRepoPath, 'pnpm', '10.12.1');
+
+  const pnpmConfigPath: string = path.join(testRepoPath, 'common/config/rush/pnpm-config.json');
+  const pnpmConfigJson: JsonObject = await JsonFile.loadAsync(pnpmConfigPath);
+  pnpmConfigJson.useWorkspaces = true;
+  pnpmConfigJson.enableGlobalVirtualStore = true;
+  await JsonFile.saveAsync(pnpmConfigJson, pnpmConfigPath, { updateExistingFile: true });
+
+  terminal.writeLine('Creating test-project-a...');
+  await helper.createTestProjectAsync(
+    testRepoPath,
+    'test-project-a',
+    '1.0.0',
+    { semver: '^7.5.4' },
+    `node -e "const fs = require('fs'); fs.mkdirSync('lib', {recursive: true}); fs.writeFileSync('lib/index.js', 'module.exports = { greet: () => \\"Hello from A\\" };');"`
+  );
+
+  terminal.writeLine('Creating test-project-b...');
+  await helper.createTestProjectAsync(
+    testRepoPath,
+    'test-project-b',
+    '1.0.0',
+    {
+      'test-project-a': 'workspace:*',
+      moment: '^2.29.4'
+    },
+    `node -e "const fs = require('fs'); fs.mkdirSync('lib', {recursive: true}); fs.writeFileSync('lib/index.js', 'module.exports = { test: () => \\"Using: \\" + require(\\'test-project-a\\').greet() };');"`
+  );
+
+  await FileSystem.ensureEmptyFolderAsync(sharedStorePath);
+
+  terminal.writeLine('');
+  terminal.writeLine("Running 'rush update' with PNPM global virtual store enabled...");
+  await helper.executeRushAsync(['update'], testRepoPath, rushEnvironment);
+
+  terminal.writeLine('');
+  terminal.writeLine("Running 'rush install' with PNPM global virtual store enabled...");
+  await helper.executeRushAsync(['install'], testRepoPath, rushEnvironment);
+
+  await helper.verifyPnpmGlobalVirtualStoreAsync(testRepoPath, sharedStorePath, [
+    'projects/test-project-a/node_modules/semver',
+    'projects/test-project-b/node_modules/moment'
+  ]);
+  await helper.verifyDependenciesAsync(testRepoPath, 'test-project-a', ['semver']);
+  await helper.verifyDependenciesAsync(testRepoPath, 'test-project-b', ['test-project-a']);
+
+  terminal.writeLine('');
+  terminal.writeLine("Running 'rush build'...");
+  await helper.executeRushAsync(['build'], testRepoPath, rushEnvironment);
+
+  await helper.verifyBuildOutputsAsync(testRepoPath, ['test-project-a', 'test-project-b']);
+  await helper.testBuiltCodeAsync(testRepoPath, 'test-project-b');
+
+  terminal.writeLine('');
+  terminal.writeLine('==========================================');
+  terminal.writeLine('✓ PNPM Global Virtual Store Integration Test PASSED');
+  terminal.writeLine('==========================================');
+  terminal.writeLine('');
+  terminal.writeLine('PNPM global virtual store works correctly with Rush workspace installs:');
+  terminal.writeLine('  - Workspace file includes enableGlobalVirtualStore');
+  terminal.writeLine('  - Shared PNPM store is populated');
+  terminal.writeLine('  - Dependencies link and resolve correctly');
+  terminal.writeLine('  - Build completed successfully');
+  terminal.writeLine('');
+}

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

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush-lib",
+      "comment": "Add PNPM global virtual store support for workspace installs and avoid unnecessary global package manager lock acquisition.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/rush-lib",
+  "email": "EscapeB@users.noreply.github.com"
+}

common/config/rush/pnpm-config.json

@@ -190,6 +190,24 @@
    */
   // "pnpmStore": "global",
 
+  /**
+   * If true, Rush will configure PNPM workspace installs to use PNPM's global virtual store.
+   * This places the virtual store under the configured PNPM store instead of under
+   * `node_modules/.pnpm` in the workspace. This can significantly reduce setup and cleanup costs
+   * when multiple Git worktrees share the same PNPM store.
+   *
+   * This option only affects workspace installs. It requires PNPM 10.12.1 or newer and a shared
+   * PNPM store, configured using either `"pnpmStore": "global"` or the `RUSH_PNPM_STORE_PATH`
+   * environment variable. If `RUSH_PNPM_STORE_PATH` is used, it must point outside the Rush repo.
+   * It is not currently compatible with the
+   * `usePnpmSyncForInjectedDependencies` experiment.
+   *
+   * PNPM documentation: https://pnpm.io/settings#enableglobalvirtualstore
+   *
+   * The default value is false.
+   */
+  // "enableGlobalVirtualStore": true,
+
   /**
    * If true, then `rush install` will report an error if manual modifications
    * were made to the PNPM shrinkwrap file without running `rush update` afterwards.