[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

@@ -562,6 +562,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": "e8913fc783fabd3c2743397b9e8494b7d39dce34",
+  "pnpmShrinkwrapHash": "5025d77ad0239eada0c6cfaf815da697ef809c24",
   "preferredVersionsHash": "550b4cee0bef4e97db6c6aad726df5149d20e7d9",
-  "packageJsonInjectedDependenciesHash": "8f951e62240e50b2601a58e625da39e294a7b50f"
+  "packageJsonInjectedDependenciesHash": "dd0075f3b513d4c2edb0a3192c25650cc1277d66"
 }

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": "79f96eccf6ba5dbdba5a8478dc7fa309e2747884",
+  "pnpmShrinkwrapHash": "f115668be4d66c7667ba49d56d3426211048e376",
   "preferredVersionsHash": "550b4cee0bef4e97db6c6aad726df5149d20e7d9"
 }

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

@@ -246,6 +246,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

@@ -46,6 +46,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",
@@ -56,6 +57,7 @@
     "js-yaml": "~3.13.1",
     "npm-check": "~6.0.1",
     "npm-package-arg": "~6.1.0",
+    "pnpm-sync-lib": "0.3.2",
     "read-package-tree": "~5.1.5",
     "rxjs": "~6.6.7",
     "semver": "~7.5.4",
@@ -64,8 +66,7 @@
     "tapable": "2.2.1",
     "tar": "~6.2.1",
     "true-case-path": "~2.2.1",
-    "uuid": "~8.3.2",
-    "pnpm-sync-lib": "0.3.2"
+    "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

@@ -27,14 +27,18 @@ import {
 } from '../api/CommandLineConfiguration';
 
 import { AddAction } from './actions/AddAction';
+import { AlertAction } from './actions/AlertAction';
+import { BridgePackageAction } from './actions/BridgePackageAction';
 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 { LinkPackageAction } from './actions/LinkPackageAction';
 import { ListAction } from './actions/ListAction';
 import { PublishAction } from './actions/PublishAction';
 import { PurgeAction } from './actions/PurgeAction';
@@ -43,12 +47,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,13 +61,10 @@ 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 { LinkPackageAction } from './actions/LinkPackageAction';
-import { BridgePackageAction } from './actions/BridgePackageAction';
+import { initializeDotEnv } from '../logic/dotenv';
 
 import { measureAsyncFn } from '../utilities/performance';
 
@@ -118,39 +119,46 @@ 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);
+
+      initializeDotEnv(terminal, rushJsonFilePath);
+
+      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/RushPnpmCommandLineParser.ts

@@ -33,6 +33,7 @@ import { Utilities } from '../utilities/Utilities';
 import type { Subspace } from '../api/Subspace';
 import type { PnpmOptionsConfiguration } from '../logic/pnpm/PnpmOptionsConfiguration';
 import { EnvironmentVariableNames } from '../api/EnvironmentConfiguration';
+import { initializeDotEnv } from '../logic/dotenv';
 
 const RUSH_SKIP_CHECKS_PARAMETER: string = '--rush-skip-checks';
 
@@ -78,10 +79,17 @@ export class RushPnpmCommandLineParser {
     this._terminal = terminal;
 
     // Are we in a Rush repo?
-    const rushConfiguration: RushConfiguration | undefined = RushConfiguration.tryLoadFromDefaultLocation({
+    const rushJsonFilePath: string | undefined = RushConfiguration.tryFindRushJsonLocation({
       // showVerbose is false because the logging message may break JSON output
       showVerbose: false
     });
+
+    initializeDotEnv(terminal, rushJsonFilePath);
+
+    const rushConfiguration: RushConfiguration | undefined = rushJsonFilePath
+      ? RushConfiguration.loadFromConfigurationFile(rushJsonFilePath)
+      : undefined;
+
     NodeJsCompatibility.warnAboutCompatibilityIssues({
       isRushLib: true,
       alreadyReportedNodeTooNewError: !!options.alreadyReportedNodeTooNewError,

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

@@ -25,6 +25,7 @@ import { Event } from '../api/EventHooks';
 import { EnvironmentVariableNames } from '../api/EnvironmentConfiguration';
 import { RushConstants } from '../logic/RushConstants';
 import { PnpmSyncUtilities } from '../utilities/PnpmSyncUtilities';
+import { initializeDotEnv } from '../logic/dotenv';
 
 interface IRushXCommandLineArguments {
   /**
@@ -77,18 +78,31 @@ export class RushXCommandLine {
   public static async launchRushXAsync(launcherVersion: string, options: ILaunchOptions): Promise<void> {
     try {
       const rushxArguments: IRushXCommandLineArguments = RushXCommandLine._parseCommandLineArguments();
-      const rushConfiguration: RushConfiguration | undefined = RushConfiguration.tryLoadFromDefaultLocation({
+      const rushJsonFilePath: string | undefined = RushConfiguration.tryFindRushJsonLocation({
         showVerbose: false
       });
+      const { isDebug, help, ignoreHooks } = rushxArguments;
+
+      const terminalProvider: ITerminalProvider = new ConsoleTerminalProvider({
+        debugEnabled: isDebug,
+        verboseEnabled: isDebug
+      });
+      const terminal: ITerminal = new Terminal(terminalProvider);
+
+      initializeDotEnv(terminal, rushJsonFilePath);
+
+      const rushConfiguration: RushConfiguration | undefined = rushJsonFilePath
+        ? RushConfiguration.loadFromConfigurationFile(rushJsonFilePath)
+        : undefined;
       const eventHooksManager: EventHooksManager | undefined = rushConfiguration
         ? new EventHooksManager(rushConfiguration)
         : undefined;
 
       const suppressHooks: boolean = process.env[EnvironmentVariableNames._RUSH_RECURSIVE_RUSHX_CALL] === '1';
-      const attemptHooks: boolean = !suppressHooks && !rushxArguments.help;
+      const attemptHooks: boolean = !suppressHooks && !help;
       if (attemptHooks) {
         try {
-          eventHooksManager?.handle(Event.preRushx, rushxArguments.isDebug, rushxArguments.ignoreHooks);
+          eventHooksManager?.handle(Event.preRushx, isDebug, ignoreHooks);
         } catch (error) {
           // eslint-disable-next-line no-console
           console.error(Colorize.red('PreRushx hook error: ' + (error as Error).message));
@@ -98,10 +112,10 @@ export class RushXCommandLine {
       // promise exception), so we start with the assumption that the exit code is 1
       // and set it to 0 only on success.
       process.exitCode = 1;
-      await RushXCommandLine._launchRushXInternalAsync(rushxArguments, rushConfiguration, options);
+      await RushXCommandLine._launchRushXInternalAsync(terminal, rushxArguments, rushConfiguration, options);
       if (attemptHooks) {
         try {
-          eventHooksManager?.handle(Event.postRushx, rushxArguments.isDebug, rushxArguments.ignoreHooks);
+          eventHooksManager?.handle(Event.postRushx, isDebug, ignoreHooks);
         } catch (error) {
           // eslint-disable-next-line no-console
           console.error(Colorize.red('PostRushx hook error: ' + (error as Error).message));
@@ -122,6 +136,7 @@ export class RushXCommandLine {
   }
 
   private static async _launchRushXInternalAsync(
+    terminal: ITerminal,
     rushxArguments: IRushXCommandLineArguments,
     rushConfiguration: RushConfiguration | undefined,
     options: ILaunchOptions
@@ -218,12 +233,6 @@ export class RushXCommandLine {
       }
     });
 
-    const terminalProvider: ITerminalProvider = new ConsoleTerminalProvider({
-      debugEnabled: rushxArguments.isDebug,
-      verboseEnabled: rushxArguments.isDebug
-    });
-    const terminal: ITerminal = new Terminal(terminalProvider);
-
     if (rushConfiguration?.isPnpm && rushConfiguration?.experimentsConfiguration) {
       const { configuration: experiments } = rushConfiguration?.experimentsConfiguration;