[rush-sdk]: add named export support for CommonJS compatibility

common/changes/@microsoft/rush/chore-optimize-named-exports_2026-01-06-12-36.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Chore: add named exports to support for `@rushstack/rush-sdk` used via ESM named import.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/config/rush/browser-approved-packages.json

@@ -58,6 +58,10 @@
       "name": "axios",
       "allowedCategories": [ "libraries" ]
     },
+    {
+      "name": "cjs-module-lexer",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "dependency-path",
       "allowedCategories": [ "libraries" ]

common/config/subspaces/build-tests-subspace/repo-state.json

@@ -1,6 +1,6 @@
 // DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
 {
-  "pnpmShrinkwrapHash": "32f13ef1f15898a4f614bf9897cc1d74d8fdf2dd",
+  "pnpmShrinkwrapHash": "402417ff6a3ef549c064c379cb9793ec4b4d64af",
   "preferredVersionsHash": "550b4cee0bef4e97db6c6aad726df5149d20e7d9",
-  "packageJsonInjectedDependenciesHash": "cb59d652ae8cf04249e1fa557d15d2958128a5e8"
+  "packageJsonInjectedDependenciesHash": "248fe4df023dec4d802dbb3f8d3f90842fd458ed"
 }

common/config/subspaces/default/repo-state.json

@@ -1,5 +1,5 @@
 // DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
 {
-  "pnpmShrinkwrapHash": "02e03149d5bf0b6a4e8dd2df668ed5350b0506c5",
+  "pnpmShrinkwrapHash": "f91ada7a0ec37139e2f0cff3fb869d1f514ee628",
   "preferredVersionsHash": "a9b67c38568259823f9cfb8270b31bf6d8470b27"
 }

libraries/rush-sdk/config/jest.config.json

@@ -1,9 +1,9 @@
 {
   "extends": "local-node-rig/profiles/default/config/jest.config.json",
 
-  "roots": ["<rootDir>/lib-shim"],
+  "roots": ["<rootDir>/lib-commonjs"],
 
-  "testMatch": ["<rootDir>/lib-shim/**/*.test.js"],
+  "testMatch": ["<rootDir>/lib-commonjs/**/*.test.js"],
 
   "collectCoverageFrom": [
     "lib-shim/**/*.js",

libraries/rush-sdk/package.json

@@ -56,6 +56,7 @@
     "@rushstack/webpack-preserve-dynamic-require-plugin": "workspace:*",
     "@types/semver": "7.5.0",
     "@types/webpack-env": "1.18.8",
+    "cjs-module-lexer": "2.1.0",
     "eslint": "~9.37.0",
     "local-node-rig": "workspace:*",
     "webpack": "~5.103.0"

libraries/rush-sdk/src/generate-stubs.ts

@@ -3,7 +3,9 @@
 
 import * as path from 'node:path';
 
-import { FileSystem, Import, Path } from '@rushstack/node-core-library';
+import { initSync, parse } from 'cjs-module-lexer';
+
+import { Encoding, FileSystem, Import, Path } from '@rushstack/node-core-library';
 
 function generateLibFilesRecursively(options: {
   parentSourcePath: string;
@@ -14,6 +16,10 @@ function generateLibFilesRecursively(options: {
   for (const folderItem of FileSystem.readFolderItems(options.parentSourcePath)) {
     const sourcePath: string = path.join(options.parentSourcePath, folderItem.name);
     const targetPath: string = path.join(options.parentTargetPath, folderItem.name);
+    const commonjsPath: string = path.join(
+      options.parentSourcePath.replace('/rush-lib/lib', '/rush-lib/lib-commonjs'),
+      folderItem.name
+    );
 
     if (folderItem.isDirectory()) {
       // create destination folder
@@ -36,11 +42,17 @@ function generateLibFilesRecursively(options: {
         const shimPathLiteral: string = JSON.stringify(Path.convertToSlashes(shimPath));
         const srcImportPathLiteral: string = JSON.stringify(srcImportPath);
 
+        const sourceCode: string = FileSystem.readFile(commonjsPath, { encoding: Encoding.Utf8 });
+        const exportedNames: string[] = extractNamedExports(sourceCode);
+        const namedExportsPlaceholder: string = exportedNames.length
+          ? `${exportedNames.map((name) => `exports.${name}`).join(' = ')} = undefined;\n\n`
+          : '';
+
         FileSystem.writeFile(
           targetPath,
           // Example:
           // module.exports = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/policy/GitEmailPolicy");
-          `module.exports = require(${shimPathLiteral})._rushSdk_loadInternalModule(${srcImportPathLiteral});`
+          `${namedExportsPlaceholder}module.exports = require(${shimPathLiteral})._rushSdk_loadInternalModule(${srcImportPathLiteral});`
         );
       }
     }
@@ -58,6 +70,7 @@ export async function runAsync(): Promise<void> {
   const stubsTargetPath: string = path.resolve(__dirname, '../lib');
   // eslint-disable-next-line no-console
   console.log('generate-stubs: Generating stub files under: ' + stubsTargetPath);
+  initSync();
   generateLibFilesRecursively({
     parentSourcePath: path.join(rushLibFolder, 'lib'),
     parentTargetPath: stubsTargetPath,
@@ -67,3 +80,8 @@ export async function runAsync(): Promise<void> {
   // eslint-disable-next-line no-console
   console.log('generate-stubs: Completed successfully.');
 }
+
+export function extractNamedExports(source: string): string[] {
+  const { exports, reexports } = parse(source);
+  return [...exports, ...reexports].filter((d) => d !== '__esModule');
+}

libraries/rush-sdk/src/test/__snapshots__/script.test.ts.snap

@@ -57,6 +57,7 @@ Loaded @microsoft/rush-lib from process.env._RUSH_LIB_PATH
   'VersionPolicyDefinitionName',
   'YarnOptionsConfiguration',
   '_FlagFile',
+  '_OperationBuildCache',
   '_OperationMetadataManager',
   '_OperationStateFile',
   '_RushGlobalFolder',
@@ -76,15 +77,6 @@ exports[`@rushstack/rush-sdk Should load via global (for plugins): stdout 1`] =
 
 exports[`@rushstack/rush-sdk Should load via install-run (for standalone tools): stderr 1`] = `""`;
 
-exports[`@rushstack/rush-sdk Should load via install-run (for standalone tools): stdout 1`] = `
-"Trying to load  @microsoft/rush-lib installed by install-run-rush
-Loaded @microsoft/rush-lib installed by install-run-rush
-[
-  '_rushSdk_loadInternalModule',
-  'foo'
-]"
-`;
-
 exports[`@rushstack/rush-sdk Should load via process.env._RUSH_LIB_PATH (for child processes): stderr 1`] = `""`;
 
 exports[`@rushstack/rush-sdk Should load via process.env._RUSH_LIB_PATH (for child processes): stdout 1`] = `

libraries/rush-sdk/src/test/build-assets-with-named-exports.test.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { Executable } from '@rushstack/node-core-library';
+
+describe('@rushstack/rush-sdk named exports check', () => {
+  it('Should import named exports correctly (lib-shim)', () => {
+    const result = Executable.spawnSync('node', [
+      '-e',
+      `
+const { RushConfiguration } = await import('@rushstack/rush-sdk');
+console.log(typeof RushConfiguration.loadFromConfigurationFile);
+`
+    ]);
+    expect(result.stdout.trim()).toEqual('function');
+    expect(result.status).toBe(0);
+  });
+
+  it('Should import named exports correctly (lib)', () => {
+    const result = Executable.spawnSync('node', [
+      '-e',
+      `
+const { RushConfiguration } = await import('@rushstack/rush-sdk/lib/api/RushConfiguration');
+console.log(typeof RushConfiguration.loadFromConfigurationFile);
+`
+    ]);
+    expect(result.stdout.trim()).toEqual('function');
+    expect(result.status).toBe(0);
+  });
+});

libraries/rush-sdk/src/test/script.test.ts

@@ -102,7 +102,9 @@ ${loadAndPrintRushSdkModule}
       }
     );
     expect(result.stderr.trim()).toMatchSnapshot('stderr');
-    expect(result.stdout.trim()).toMatchSnapshot('stdout');
+    expect(result.stdout.trim()).toContain(
+      'Trying to load  @microsoft/rush-lib installed by install-run-rush'
+    );
     expect(result.status).toBe(0);
   });
 });