[rush] Add support for .env files.

common/changes/@microsoft/rush/dotenv_2025-03-10-22-13.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add support for setting environment variables via `<repo-root>/.env` and `~/.rush-user/.env` files.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

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

@@ -506,6 +506,10 @@
       "name": "doc-plugin-rush-stack",
       "allowedCategories": [ "libraries" ]
     },
+    {
+      "name": "dotenv",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "eslint",
       "allowedCategories": [ "libraries", "tests", "vscode-extensions" ]

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": "b48c35b584583839e5d4a9e651d78a779d206b2e",
+  "pnpmShrinkwrapHash": "8465c51e473155e55c752d1ba8a929a9dde031fd",
   "preferredVersionsHash": "54149ea3f01558a859c96dee2052b797d4defe68",
-  "packageJsonInjectedDependenciesHash": "a8af9805efae30377fcf83e1a927721f67381aee"
+  "packageJsonInjectedDependenciesHash": "eacd9bb78498347b62458a678a12bdca7293da5d"
 }

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": "9429dfa99a546617d190d3eb990cc5fbc6e0ac7c",
+  "pnpmShrinkwrapHash": "5f6737a24eea6a2afef9ab8a02f07ec3306addd8",
   "preferredVersionsHash": "54149ea3f01558a859c96dee2052b797d4defe68"
 }

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

@@ -245,6 +245,7 @@ export class EnvironmentConfiguration {
     // @internal
     static _getRushGlobalFolderOverride(processEnv: IEnvironment): string | undefined;
     static get gitBinaryPath(): string | undefined;
+    static get hasBeenValidated(): boolean;
     // (undocumented)
     static parseBooleanEnvironmentVariable(name: string, value: string | undefined): boolean | undefined;
     static get pnpmStorePathOverride(): string | undefined;

libraries/rush-lib/package.json

@@ -45,6 +45,7 @@
     "builtin-modules": "~3.1.0",
     "cli-table": "~0.3.1",
     "dependency-path": "~9.2.8",
+    "dotenv": "~16.4.7",
     "fast-glob": "~3.3.1",
     "figures": "3.0.0",
     "git-repo-info": "~2.1.0",
@@ -55,6 +56,7 @@
     "js-yaml": "~3.13.1",
     "npm-check": "~6.0.1",
     "npm-package-arg": "~6.1.0",
+    "pnpm-sync-lib": "0.2.9",
     "read-package-tree": "~5.1.5",
     "rxjs": "~6.6.7",
     "semver": "~7.5.4",
@@ -63,8 +65,7 @@
     "tapable": "2.2.1",
     "tar": "~6.2.1",
     "true-case-path": "~2.2.1",
-    "uuid": "~8.3.2",
-    "pnpm-sync-lib": "0.2.9"
+    "uuid": "~8.3.2"
   },
   "devDependencies": {
     "@pnpm/lockfile.types": "~1.0.3",

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

@@ -260,6 +260,13 @@ export class EnvironmentConfiguration {
 
   private static _tarBinaryPath: string | undefined;
 
+  /**
+   * If true, the environment configuration has been validated and initialized.
+   */
+  public static get hasBeenValidated(): boolean {
+    return EnvironmentConfiguration._hasBeenValidated;
+  }
+
   /**
    * An override for the common/temp folder path.
    */

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

@@ -52,10 +52,6 @@ export class RushUserConfiguration {
 
   public static getRushUserFolderPath(): string {
     const homeFolderPath: string = Utilities.getHomeFolder();
-    const rushUserSettingsFilePath: string = path.join(
-      homeFolderPath,
-      RushConstants.rushUserConfigurationFolderName
-    );
-    return rushUserSettingsFilePath;
+    return `${homeFolderPath}/${RushConstants.rushUserConfigurationFolderName}`;
   }
 }

libraries/rush-lib/src/cli/RushCommandLineParser.ts

@@ -16,6 +16,7 @@ import {
   Colorize,
   type ITerminal
 } from '@rushstack/terminal';
+import dotenv from 'dotenv';
 
 import { RushConfiguration } from '../api/RushConfiguration';
 import { RushConstants } from '../logic/RushConstants';
@@ -27,13 +28,15 @@ import {
 } from '../api/CommandLineConfiguration';
 
 import { AddAction } from './actions/AddAction';
+import { AlertAction } from './actions/AlertAction';
 import { ChangeAction } from './actions/ChangeAction';
 import { CheckAction } from './actions/CheckAction';
 import { DeployAction } from './actions/DeployAction';
 import { InitAction } from './actions/InitAction';
 import { InitAutoinstallerAction } from './actions/InitAutoinstallerAction';
 import { InitDeployAction } from './actions/InitDeployAction';
 import { InstallAction } from './actions/InstallAction';
+import { InstallAutoinstallerAction } from './actions/InstallAutoinstallerAction';
 import { LinkAction } from './actions/LinkAction';
 import { ListAction } from './actions/ListAction';
 import { PublishAction } from './actions/PublishAction';
@@ -43,12 +46,12 @@ import { ScanAction } from './actions/ScanAction';
 import { UnlinkAction } from './actions/UnlinkAction';
 import { UpdateAction } from './actions/UpdateAction';
 import { UpdateAutoinstallerAction } from './actions/UpdateAutoinstallerAction';
-import { VersionAction } from './actions/VersionAction';
 import { UpdateCloudCredentialsAction } from './actions/UpdateCloudCredentialsAction';
 import { UpgradeInteractiveAction } from './actions/UpgradeInteractiveAction';
-import { AlertAction } from './actions/AlertAction';
+import { VersionAction } from './actions/VersionAction';
 
 import { GlobalScriptAction } from './scriptActions/GlobalScriptAction';
+import { PhasedScriptAction } from './scriptActions/PhasedScriptAction';
 import type { IBaseScriptActionOptions } from './scriptActions/BaseScriptAction';
 
 import { Telemetry } from '../logic/Telemetry';
@@ -57,11 +60,11 @@ import { NodeJsCompatibility } from '../logic/NodeJsCompatibility';
 import { SetupAction } from './actions/SetupAction';
 import { type ICustomCommandLineConfigurationInfo, PluginManager } from '../pluginFramework/PluginManager';
 import { RushSession } from '../pluginFramework/RushSession';
-import { PhasedScriptAction } from './scriptActions/PhasedScriptAction';
 import type { IBuiltInPluginConfiguration } from '../pluginFramework/PluginLoader/BuiltInPluginLoader';
 import { InitSubspaceAction } from './actions/InitSubspaceAction';
 import { RushAlerts } from '../utilities/RushAlerts';
-import { InstallAutoinstallerAction } from './actions/InstallAutoinstallerAction';
+import { RushUserConfiguration } from '../api/RushUserConfiguration';
+import { EnvironmentConfiguration } from '../api/EnvironmentConfiguration';
 
 /**
  * Options for `RushCommandLineParser`.
@@ -113,39 +116,61 @@ export class RushCommandLineParser extends CommandLineParser {
       description: 'Hide rush startup information'
     });
 
-    this._terminalProvider = new ConsoleTerminalProvider();
-    this._terminal = new Terminal(this._terminalProvider);
+    const terminalProvider: ConsoleTerminalProvider = new ConsoleTerminalProvider();
+    this._terminalProvider = terminalProvider;
+    const terminal: Terminal = new Terminal(this._terminalProvider);
+    this._terminal = terminal;
     this._rushOptions = this._normalizeOptions(options || {});
+    const { cwd, alreadyReportedNodeTooNewError, builtInPluginConfigurations } = this._rushOptions;
 
+    let rushJsonFilePath: string | undefined;
     try {
-      const rushJsonFilename: string | undefined = RushConfiguration.tryFindRushJsonLocation({
-        startingFolder: this._rushOptions.cwd,
+      rushJsonFilePath = RushConfiguration.tryFindRushJsonLocation({
+        startingFolder: cwd,
         showVerbose: !this._restrictConsoleOutput
       });
-      if (rushJsonFilename) {
-        this.rushConfiguration = RushConfiguration.loadFromConfigurationFile(rushJsonFilename);
+
+      if (EnvironmentConfiguration.hasBeenValidated) {
+        throw new Error(
+          `The ${EnvironmentConfiguration.name} was initialized before .env files were loaded. Rush environment ` +
+            'variables may have unexpected values.'
+        );
+      }
+
+      if (rushJsonFilePath) {
+        const rushJsonFolder: string = path.dirname(rushJsonFilePath);
+        dotenv.config({ path: `${rushJsonFolder}/.env` });
+      }
+
+      const rushUserFolder: string = RushUserConfiguration.getRushUserFolderPath();
+      dotenv.config({ path: `${rushUserFolder}/.env` });
+
+      // TODO: Consider adding support for repo-specific `.rush-user` `.env` files.
+
+      if (rushJsonFilePath) {
+        this.rushConfiguration = RushConfiguration.loadFromConfigurationFile(rushJsonFilePath);
       }
     } catch (error) {
       this._reportErrorAndSetExitCode(error as Error);
     }
 
     NodeJsCompatibility.warnAboutCompatibilityIssues({
       isRushLib: true,
-      alreadyReportedNodeTooNewError: this._rushOptions.alreadyReportedNodeTooNewError,
+      alreadyReportedNodeTooNewError,
       rushConfiguration: this.rushConfiguration
     });
 
     this.rushGlobalFolder = new RushGlobalFolder();
 
     this.rushSession = new RushSession({
       getIsDebugMode: () => this.isDebug,
-      terminalProvider: this._terminalProvider
+      terminalProvider
     });
     this.pluginManager = new PluginManager({
       rushSession: this.rushSession,
       rushConfiguration: this.rushConfiguration,
-      terminal: this._terminal,
-      builtInPluginConfigurations: this._rushOptions.builtInPluginConfigurations,
+      terminal,
+      builtInPluginConfigurations,
       restrictConsoleOutput: this._restrictConsoleOutput,
       rushGlobalFolder: this.rushGlobalFolder
     });

libraries/rush-lib/src/cli/actions/test/AddAction.test.ts

@@ -3,11 +3,13 @@
 
 import '../../test/mockRushCommandLineParser';
 
+import { LockFile } from '@rushstack/node-core-library';
+
 import { PackageJsonUpdater } from '../../../logic/PackageJsonUpdater';
 import type { IPackageJsonUpdaterRushAddOptions } from '../../../logic/PackageJsonUpdaterTypes';
 import { RushCommandLineParser } from '../../RushCommandLineParser';
 import { AddAction } from '../AddAction';
-import { LockFile } from '@rushstack/node-core-library';
+import { EnvironmentConfiguration } from '../../../api/EnvironmentConfiguration';
 
 describe(AddAction.name, () => {
   describe('basic "rush add" tests', () => {
@@ -32,6 +34,7 @@ describe(AddAction.name, () => {
       jest.clearAllMocks();
       process.exitCode = oldExitCode;
       process.argv = oldArgs;
+      EnvironmentConfiguration.reset();
     });
 
     describe("'add' action", () => {

libraries/rush-lib/src/cli/actions/test/RemoveAction.test.ts

@@ -3,13 +3,15 @@
 
 import '../../test/mockRushCommandLineParser';
 
+import { LockFile } from '@rushstack/node-core-library';
+
 import { PackageJsonUpdater } from '../../../logic/PackageJsonUpdater';
 import type { IPackageJsonUpdaterRushRemoveOptions } from '../../../logic/PackageJsonUpdaterTypes';
 import { RushCommandLineParser } from '../../RushCommandLineParser';
 import { RemoveAction } from '../RemoveAction';
 import { VersionMismatchFinderProject } from '../../../logic/versionMismatch/VersionMismatchFinderProject';
 import { DependencyType } from '../../../api/PackageJsonEditor';
-import { LockFile } from '@rushstack/node-core-library';
+import { EnvironmentConfiguration } from '../../../api/EnvironmentConfiguration';
 
 describe(RemoveAction.name, () => {
   describe('basic "rush remove" tests', () => {
@@ -36,6 +38,7 @@ describe(RemoveAction.name, () => {
       jest.clearAllMocks();
       process.exitCode = oldExitCode;
       process.argv = oldArgs;
+      EnvironmentConfiguration.reset();
     });
 
     describe("'remove' action", () => {

libraries/rush-lib/src/cli/test/CommandLineHelp.test.ts

@@ -4,6 +4,7 @@
 import { AnsiEscape } from '@rushstack/terminal';
 
 import { RushCommandLineParser } from '../RushCommandLineParser';
+import { EnvironmentConfiguration } from '../../api/EnvironmentConfiguration';
 
 describe('CommandLineHelp', () => {
   let oldCwd: string | undefined;
@@ -33,6 +34,8 @@ describe('CommandLineHelp', () => {
     if (oldCwd) {
       process.chdir(oldCwd);
     }
+
+    EnvironmentConfiguration.reset();
   });
 
   it('prints the global help', () => {

libraries/rush-lib/src/cli/test/RushCommandLineParser.test.ts

@@ -27,6 +27,7 @@ import { FileSystem, JsonFile, Path } from '@rushstack/node-core-library';
 import { Autoinstaller } from '../../logic/Autoinstaller';
 import type { ITelemetryData } from '../../logic/Telemetry';
 import { getCommandLineParserInstanceAsync } from './TestUtils';
+import { EnvironmentConfiguration } from '../../api/EnvironmentConfiguration';
 
 function pathEquals(actual: string, expected: string): void {
   expect(Path.convertToSlashes(actual)).toEqual(Path.convertToSlashes(expected));
@@ -40,6 +41,7 @@ describe('RushCommandLineParser', () => {
   describe('execute', () => {
     afterEach(() => {
       jest.clearAllMocks();
+      EnvironmentConfiguration.reset();
     });
 
     describe('in basic repo', () => {

libraries/rush-lib/src/cli/test/RushPluginCommandLineParameters.test.ts

@@ -7,6 +7,7 @@ import path from 'path';
 import { FileSystem, LockFile } from '@rushstack/node-core-library';
 import { RushCommandLineParser } from '../RushCommandLineParser';
 import { Autoinstaller } from '../../logic/Autoinstaller';
+import { EnvironmentConfiguration } from '../../api/EnvironmentConfiguration';
 
 describe('PluginCommandLineParameters', () => {
   let originCWD: string | undefined;
@@ -61,6 +62,8 @@ describe('PluginCommandLineParameters', () => {
       originCWD = undefined;
       process.argv = _argv;
     }
+
+    EnvironmentConfiguration.reset();
   });
 
   afterAll(() => {

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

@@ -5,7 +5,7 @@ import { LockFile, Async, FileSystem } from '@rushstack/node-core-library';
 import { RushUserConfiguration } from '../../api/RushUserConfiguration';
 import { CredentialCache } from '../CredentialCache';
 
-const FAKE_RUSH_USER_FOLDER: string = '~/.rush-user';
+const FAKE_RUSH_USER_FOLDER: string = 'temp/.test-rush-user';
 const FAKE_CREDENTIALS_CACHE_FILE: string = `${FAKE_RUSH_USER_FOLDER}/credentials.json`;
 
 describe(CredentialCache.name, () => {