feat(CLI): add new --env-dir option (#2891)

e2e/cases/cli/custom-env-dir/env/.env

@@ -0,0 +1,2 @@
+NORMAL_NAME=jack
+REACT_APP_NAME=rose

e2e/cases/cli/custom-env-dir/index.test.ts

@@ -0,0 +1,16 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { expect, test } from '@playwright/test';
+
+test('should allow to custom env directory', async () => {
+  execSync('npx rsbuild build --env-dir env', {
+    cwd: __dirname,
+  });
+  const content = fs.readFileSync(
+    path.join(__dirname, 'dist/static/js/index.js'),
+    'utf-8',
+  );
+  expect(content).not.toContain('jack');
+  expect(content).toContain('rose');
+});

e2e/cases/cli/custom-env-dir/rsbuild.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig, loadEnv } from '@rsbuild/core';
+
+const { publicVars } = loadEnv({ prefixes: ['REACT_APP_'] });
+
+export default defineConfig({
+  source: {
+    define: publicVars,
+  },
+  output: {
+    filenameHash: false,
+  },
+});

e2e/cases/cli/custom-env-dir/src/index.js

@@ -0,0 +1 @@
+console.log(process.env.REACT_APP_NAME, process.env.NORMAL_NAME);

packages/core/src/cli/commands.ts

@@ -8,6 +8,7 @@ import { init } from './init';
 
 export type CommonOptions = {
   config?: string;
+  envDir?: string;
   envMode?: string;
   open?: boolean | string;
   host?: string;
@@ -37,7 +38,8 @@ const applyCommonOptions = (command: Command) => {
     .option(
       '--env-mode <mode>',
       'specify the env mode to load the `.env.[mode]` file',
-    );
+    )
+    .option('--env-dir <dir>', 'specify the directory to load `.env` files');
 };
 
 const applyServerOptions = (command: Command) => {

packages/core/src/cli/init.ts

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { loadConfig, watchFiles } from '../config';
 import { isDev } from '../helpers';
 import { loadEnv } from '../loadEnv';
@@ -8,6 +9,13 @@ import type { CommonOptions } from './commands';
 
 let commonOpts: CommonOptions = {};
 
+const getEnvDir = (cwd: string, envDir?: string) => {
+  if (envDir) {
+    return path.isAbsolute(envDir) ? envDir : path.resolve(cwd, envDir);
+  }
+  return cwd;
+};
+
 export async function init({
   cliOptions,
   isRestart,
@@ -22,8 +30,8 @@ export async function init({
   try {
     const root = process.cwd();
     const envs = loadEnv({
-      cwd: root,
-      mode: cliOptions?.envMode,
+      cwd: getEnvDir(root, commonOpts.envDir),
+      mode: commonOpts.envMode,
     });
 
     if (isDev()) {

website/docs/en/guide/advanced/env-vars.mdx

@@ -119,6 +119,18 @@ It is recommended to use `--env-mode` to set the env mode, and not to modify `pr
 
 :::
 
+### Env Directory
+
+By default, the `.env` file is located in the root directory of the project. You can specify the env directory by using the `--env-dir <dir>` option in the CLI.
+
+For example, to specify the env directory as `config`:
+
+```bash
+npx rsbuild dev --env-dir config
+```
+
+In this case, Rsbuild will read the `./config/.env` and other env files.
+
 ### Example
 
 For example, create a `.env` file and add the following contents:

website/docs/en/guide/basic/cli.mdx

@@ -40,6 +40,7 @@ Options:
   --host <host>         specify the host that the Rsbuild Server listens to
   -c --config <config>  specify the configuration file, can be a relative or absolute path
   --env-mode <mode>     specify the env mode to load the `.env.[mode]` file
+  --env-dir <dir>       specify the directory to load `.env` files
   -h, --help            display help for command
 ```
 
@@ -74,6 +75,7 @@ Options:
   -w --watch            turn on watch mode, watch for changes and rebuild
   -c --config <config>  specify the configuration file, can be a relative or absolute path
   --env-mode <mode>     specify the env mode to load the `.env.[mode]` file
+  --env-dir <dir>       specify the directory to load `.env` files
   -h, --help            display help for command
 ```
 
@@ -90,6 +92,7 @@ Options:
   --host <host>         specify the host that the Rsbuild Server listens to
   -c --config <config>  specify the configuration file, can be a relative or absolute path
   --env-mode <mode>     specify the env mode to load the `.env.[mode]` file
+  --env-dir <dir>       specify the directory to load `.env` files
   -h, --help            display help for command
 ```
 
@@ -110,6 +113,7 @@ Options:
   --verbose             Show the full function in the result
   -c --config <config>  specify the configuration file, can be a relative or absolute path
   --env-mode <mode>     specify the env mode to load the `.env.[mode]` file
+  --env-dir <dir>       specify the directory to load `.env` files
   -h, --help            show command help
 ```
 

website/docs/zh/guide/advanced/env-vars.mdx

@@ -119,6 +119,18 @@ Rsbuild 会依次读取以下文件：
 
 :::
 
+### Env 目录
+
+默认情况下，`.env` 文件位于项目的根目录。你可以通过 CLI 的 `--env-dir <dir>` 选项来指定 env 目录。
+
+比如，指定 env 目录为 `config`：
+
+```bash
+npx rsbuild dev --env-dir config
+```
+
+这种情况下，Rsbuild 会读取 `./config/.env` 等 env 文件。
+
 ### 示例
 
 比如创建 `.env` 文件并添加以下内容：

website/docs/zh/guide/basic/cli.mdx

@@ -40,6 +40,7 @@ Options:
   --host <host>         指定 Rsbuild Server 启动时监听的 host
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
+  --env-dir <dir>       指定目录来加载 `.env` 文件
   -h, --help            显示命令帮助
 ```
 
@@ -74,6 +75,7 @@ Options:
   -w --watch            开启 watch 模式, 监听文件变更并重新构建
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
+  --env-dir <dir>       指定目录来加载 `.env` 文件
   -h, --help            显示命令帮助
 ```
 
@@ -90,6 +92,7 @@ Options:
   --host <host>         指定 Rsbuild Server 启动时监听的 host
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
+  --env-dir <dir>       指定目录来加载 `.env` 文件
   -h, --help            显示命令帮助
 ```
 
@@ -110,6 +113,7 @@ Options:
   --verbose             在结果中展示函数的完整内容
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
+  --env-dir <dir>       指定目录来加载 `.env` 文件
   -h, --help            显示命令帮助
 ```