From 6940037ff6152cc9aebc0cef8fa6c22095f805ea Mon Sep 17 00:00:00 2001 From: neverland Date: Sat, 15 Mar 2025 16:28:04 +0800 Subject: [PATCH] docs: add `loadEnv` option in `createRsbuild` --- packages/core/src/types/rsbuild.ts | 4 +-- website/docs/en/api/javascript-api/core.mdx | 36 +++++++++++++++++-- website/docs/zh/api/javascript-api/core.mdx | 38 +++++++++++++++++++-- 3 files changed, 71 insertions(+), 7 deletions(-) diff --git a/packages/core/src/types/rsbuild.ts b/packages/core/src/types/rsbuild.ts index cc4c45df6d..e3d532fabd 100644 --- a/packages/core/src/types/rsbuild.ts +++ b/packages/core/src/types/rsbuild.ts @@ -129,8 +129,8 @@ export type CreateRsbuildOptions = { */ rsbuildConfig?: RsbuildConfig | (() => Promise); /** - * Whether to call `loadEnv` to load environment variables and define them - * as global variables. + * Whether to call `loadEnv` to load env variables and define them + * as global variables via `source.define`. * @default false */ loadEnv?: boolean | LoadEnvOptions; diff --git a/website/docs/en/api/javascript-api/core.mdx b/website/docs/en/api/javascript-api/core.mdx index 61d53abf58..57a057b669 100644 --- a/website/docs/en/api/javascript-api/core.mdx +++ b/website/docs/en/api/javascript-api/core.mdx @@ -35,12 +35,14 @@ type CreateRsbuildOptions = { cwd?: string; environment?: string[]; rsbuildConfig?: RsbuildConfig | (() => Promise); + loadEnv?: boolean | LoadEnvOptions; }; ``` - `cwd`: The root path of the current build, defaults to `process.cwd()`. - `environment`: Only build specified [environments](/guide/advanced/environments). If not specified or passing an empty array, all environments will be built. - `rsbuildConfig`: Rsbuild configuration object. Refer to [Configuration Overview](/config/) for all available configuration options. +- `loadEnv`：Whether to call the [loadEnv](/api/javascript-api/core#loadenv) method to load env variables and define them as global variables via [source.define](/config/source/define). ### Load configuration async @@ -58,6 +60,33 @@ const rsbuild = await createRsbuild({ }); ``` +### Load env variables + +The `loadEnv` option in `createRsbuild` helps you call the [loadEnv](/api/javascript-api/core#loadenv) method to load env variables: + +```ts +const rsbuild = await createRsbuild({ + loadEnv: true, +}); +``` + +Passing `loadEnv: true` will automatically complete the following steps: + +1. Call the `loadEnv` method to load env variables. +2. Add [source.define](/config/source/define) configuration, define the `publicVars` returned by `loadEnv` as global variables. +3. Watch the `.env` file for changes, and restart the dev server when the file changes, and invalidate the build cache. +4. Automatically call the `cleanup` method returned by `loadEnv` when closing the build or dev server. + +You can also pass in the options of the [loadEnv](/api/javascript-api/core#loadenv) method, for example: + +```ts +const rsbuild = await createRsbuild({ + loadEnv: { + prefixes: ['PUBLIC_', 'REACT_APP_'], + }, +}); +``` + ## loadConfig Load Rsbuild configuration file. @@ -135,7 +164,7 @@ export default defineConfig(({ meta }) => { ## loadEnv -Load the `.env` file and return all environment variables starting with the specified prefixes. +Load the [.env](/guide/advanced/env-vars#env-file) file and return all environment variables starting with the specified prefixes. - **Type:** @@ -222,7 +251,10 @@ const mergedConfig = mergeRsbuildConfig( This method will also load files such as `.env.local` and `.env.[mode]`, see [Environment Variables](/guide/advanced/env-vars) for details. :::tip -Rsbuild CLI will automatically call the `loadEnv()` method. If you are using the Rsbuild CLI, you can set the `mode` parameter through the [--env-mode](/guide/advanced/env-vars#env-mode) option. + +- Rsbuild CLI will automatically call the `loadEnv()` method. If you are using the Rsbuild CLI, you can set the `mode` parameter through the [--env-mode](/guide/advanced/env-vars#env-mode) option. +- The `loadEnv` option in [createRsbuild](#creatersbuild) will help you call the `loadEnv()` method and handle related operations. + ::: ### Specify the target object diff --git a/website/docs/zh/api/javascript-api/core.mdx b/website/docs/zh/api/javascript-api/core.mdx index 08c162f641..e8923e7f4f 100644 --- a/website/docs/zh/api/javascript-api/core.mdx +++ b/website/docs/zh/api/javascript-api/core.mdx @@ -26,7 +26,7 @@ const rsbuild = await createRsbuild({ }); ``` -### Options +### 选项 `createRsbuild` 的第一个参数是一个 `options` 对象，你可以传入以下选项： @@ -35,12 +35,14 @@ type CreateRsbuildOptions = { cwd?: string; environment?: string[]; rsbuildConfig?: RsbuildConfig | (() => Promise); + loadEnv?: boolean | LoadEnvOptions; }; ``` - `cwd`：当前执行构建的根路径，默认值为 `process.cwd()` - `environment`：只构建指定的 [environments](/guide/advanced/environments)，如果未指定或传入空数组，则构建所有环境。 - `rsbuildConfig`：Rsbuild 配置对象。参考 [配置总览](/config/) 查看所有可用的配置项。 +- `loadEnv`：是否调用 [loadEnv](/api/javascript-api/core#loadenv) 方法来加载环境变量，并通过 [source.define](/config/source/define) 定义为全局变量。 ### 异步加载配置 @@ -58,6 +60,33 @@ const rsbuild = await createRsbuild({ }); ``` +### 加载环境变量 + +`createRsbuild` 的 `loadEnv` 选项可以帮助你调用 [loadEnv](/api/javascript-api/core#loadenv) 方法来加载环境变量： + +```ts +const rsbuild = await createRsbuild({ + loadEnv: true, +}); +``` + +传入 `loadEnv: true` 会自动完成如下步骤： + +1. 调用 `loadEnv` 方法来加载环境变量。 +2. 添加 [source.define](/config/source/define) 配置，将 `loadEnv` 返回的 `publicVars` 定义为全局变量。 +3. 监听 `.env` 文件的变化，在文件变化时重新启动开发服务器，并使构建缓存失效。 +4. 在关闭构建或开发服务器时，自动调用 `loadEnv` 返回的 `cleanup` 方法来清除环境变量。 + +你也可以传入 [loadEnv](/api/javascript-api/core#loadenv) 方法的选项，比如： + +```ts +const rsbuild = await createRsbuild({ + loadEnv: { + prefixes: ['PUBLIC_', 'REACT_APP_'], + }, +}); +``` + ## loadConfig 加载 Rsbuild 配置文件。 @@ -135,7 +164,7 @@ export default defineConfig(({ meta }) => { ## loadEnv -加载 `.env` 文件，并返回所有以 prefixes 开头的环境变量。 +加载 [.env](/guide/advanced/env-vars#env-文件) 文件，并返回所有以 `prefixes` 开头的环境变量。 - **类型：** @@ -222,7 +251,10 @@ const mergedConfig = mergeRsbuildConfig( 该方法也会加载 `.env.local` 和 `.env.[mode]` 等文件，详见 [环境变量](/guide/advanced/env-vars)。 :::tip -Rsbuild CLI 会自动调用 `loadEnv()` 方法，如果你在使用 Rsbuild CLI，可以通过 [--env-mode](/guide/advanced/env-vars#env-模式) 选项来设置 `mode` 参数。 + +- Rsbuild CLI 会自动调用 `loadEnv()` 方法，如果你在使用 Rsbuild CLI，可以通过 [--env-mode](/guide/advanced/env-vars#env-模式) 选项来设置 `mode` 参数。 +- [createRsbuild](#creatersbuild) 的 `loadEnv` 选项会帮助你调用 `loadEnv()` 方法，并处理相关操作。 + ::: ### 指定目标对象