diff --git a/website/docs/en/guide/basic/cli.mdx b/website/docs/en/guide/basic/cli.mdx index 701b42c81..93b681d63 100644 --- a/website/docs/en/guide/basic/cli.mdx +++ b/website/docs/en/guide/basic/cli.mdx @@ -1,6 +1,6 @@ # CLI -Rslib comes with a lightweight CLI that includes commands such as build and inspect. +Rslib comes with a lightweight CLI that includes commands such as [rslib build](#rslib-build) and [rslib inspect](#rslib-inspect). ## rslib -h @@ -45,15 +45,24 @@ Options: -h, --help display help for command ``` +### Watch Mode + +You can use `rslib build --watch` or `rslib build -w` to enable watch mode for watching for changes and rebuild. + +```bash +npx rslib build -w +``` + ### Environment Variables Rslib supports injecting env variables or expressions into the code during build, which is helpful for distinguishing the running environment or replacing constants. -You can see more details in [Environment Variables](https://rsbuild.dev/guide/advanced/env-vars#environment-variables). +You can see more details in [Rsbuild - Environment Variables](https://rsbuild.dev/guide/advanced/env-vars). ::: note -`process.env.NODE_ENV` will be preserved in the build output when [format](/config/lib/format) is set to `esm` or `cjs`. For `mf` or `umd` format, it will be preserved to make output directly usable. +- If [format](/config/lib/format) is `esm` or `cjs`, `process.env.NODE_ENV` will be preserved in the build output. +- If [format](/config/lib/format) is `mf` or `umd`, `process.env.NODE_ENV` will be replaced to ensure that the output can run in the browser. ::: @@ -126,14 +135,6 @@ console.log(import.meta.env.BAR); // '2' console.log(process.env.BAR); // '2' ``` -### Watch Mode - -You can use `rslib build --watch` to turn on watch mode for watching for changes and rebuild. - -### Filter Libraries - -You can use the `--lib` option to build specific libraries. The `--lib` option can be repeated to build multiple libraries. Check out the [lib.id](/config/lib/id) to learn how to get or set the library ID. - ## rslib inspect The `rslib inspect` command is used to view the Rsbuild config and Rspack config of the Rslib project. @@ -191,15 +192,11 @@ Inspect config succeed, open following files to view the content: - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs ``` -### Filter Libraries - -You can use the `--lib` option to inspect specific libraries. The `--lib` option can be repeated to inspect multiple libraries. Check out the [lib.id](/config/lib/id) to learn how to get or set the library ID. - ## rslib mf dev -The `rslib mf dev` command is utilized to start Rsbuild dev server of Module Federation format. +The `rslib mf dev` command is utilized to start Rsbuild dev server for the [Module Federation](/guide/advanced/module-federation) format. -This enables you to develop your mf format module within the host app more rapidly. +This enables you to develop and debug your mf format module within the host app. ```text Usage: rslib mf [options] @@ -213,3 +210,23 @@ Options: --env-dir specify the directory to load `.env` files -h, --help display help for command ``` + +## Common Options + +### Filter Libraries + +Rslib provides the `--lib` option to run command for specified libraries. + +```bash +# Only build the library with id `esm` +npx rslib build --lib esm +``` + +The `--lib` option can be repeated to specify multiple libraries. + +```bash +# Build the libraries with id `esm` and `cjs` +npx rslib build --lib esm --lib cjs +``` + +> Check out the [lib.id](/config/lib/id) to learn how to get or set the library ID. diff --git a/website/docs/zh/guide/basic/cli.mdx b/website/docs/zh/guide/basic/cli.mdx index 80898d198..34040b08a 100644 --- a/website/docs/zh/guide/basic/cli.mdx +++ b/website/docs/zh/guide/basic/cli.mdx @@ -1 +1,232 @@ # 命令行工具 + +Rslib 提供了一个轻量级的命令行工具,包含 [rslib build](#rslib-build) 和 [rslib inspect](#rslib-inspect) 等命令。 + +## rslib -h + +如果你需要查看所有可用的 CLI 命令,请在项目目录中运行以下命令: + +```bash +npx rslib -h +``` + +输出如下: + +```text +Usage: rslib [options] + +Options: + -V, --version 显示版本号 + -h, --help 显示命令帮助 + +Commands: + build [options] 构建用于生产环境的产物 + inspect [options] 检查 Rslib 项目的 Rsbuild 配置和 Rspack 配置 + mf [options] 为 Module Federation 格式的库启用 Rsbuild 开发服务器。 + help [command] 显示命令帮助 +``` + +## rslib build + +`rslib build` 命令默认会在 `dist/` 目录下输出构建产物。 + +```text +Usage: rslib build [options] + +构建用于生产环境的产物 + +Options: + -c --config 指定配置文件路径,可以为相对路径或绝对路径 + -r --root 指定项目根目录,可以是绝对路径或者相对于 cwd 的路径 + --env-mode 指定 env 模式来加载 `.env.[mode]` 文件 + --env-dir 指定目录来加载 `.env` 文件 + --lib 仅构建指定的库(可以重复) + -w --watch 开启 watch 模式, 监听文件变更并重新构建 + -h, --help 显示命令帮助 +``` + +### Watch 模式 + +你可以使用 `rslib build --watch` 或 `rslib build -w` 来开启 watch 模式,监听文件变更并重新构建。 + +```bash +npx rslib build -w +``` + +### 环境变量 + +Rslib 支持在构建过程中向代码中注入环境变量或表达式,这对于区分运行环境、替换常量值等场景很有帮助。 + +你可以在 [Rsbuild - 环境变量](https://rsbuild.dev/zh/guide/advanced/env-vars) 了解更多详细信息。 + +::: note + +- 当 [format](/config/lib/format) 设置为 `esm` 或 `cjs` 时,`process.env.NODE_ENV` 会在构建输出中被保留。 +- 当 [format](/config/lib/format) 设置为 `mf` 或 `umd` 时,`process.env.NODE_ENV` 将被替换,以确保构建输出可以在浏览器中运行。 + +::: + +#### Env 模式 + +Rslib 支持读取 `.env.[mode]` 和 `.env.[mode].local` 文件。你可以通过 CLI 的 `--env-mode ` 选项来指定 env 模式。 + +比如,设置 env 模式为 `test`: + +```bash +npx rslib build --env-mode test +``` + +Rslib 会依次读取以下文件: + +- `.env` +- `.env.local` +- `.env.test` +- `.env.test.local` + +:::tip + +`--env-mode` 选项的优先级高于 `process.env.NODE_ENV`。 + +推荐使用 `--env-mode` 来指定 env 模式,不建议修改 `process.env.NODE_ENV`。 + +::: + +#### Env 目录 + +默认情况下,`.env` 文件位于项目的根目录。你可以通过 CLI 的 `--env-dir ` 选项来指定 env 目录。 + +比如,指定 env 目录为 `config`: + +```bash +npx rslib build --env-dir config +``` + +这种情况下,Rslib 会读取 `./config/.env` 等 env 文件。 + +##### 示例 + +比如创建 `.env` 文件并添加以下内容: + +```shell title=".env" +FOO=hello +BAR=1 +``` + +然后在 `rslib.config.ts` 文件中,你可以通过 `import.meta.env.[name]` 或 `process.env.[name]` 访问到上述环境变量: + +```ts title="rslib.config.ts" +console.log(import.meta.env.FOO); // 'hello' +console.log(import.meta.env.BAR); // '1' + +console.log(process.env.FOO); // 'hello' +console.log(process.env.BAR); // '1' +``` + +此时,创建一个 `.env.local` 文件,添加以下内容: + +```shell title=".env.local" +BAR=2 +``` + +`BAR` 的值会被覆盖为 `'2'`: + +```ts title="rslib.config.ts" +console.log(import.meta.env.BAR); // '2' +console.log(process.env.BAR); // '2' +``` + +## rslib inspect + +`rslib inspect` 命令用于查看 Rslib 项目的 Rsbuild 配置和 Rspack 配置。 + +```text +Usage: rslib inspect [options] + +查看 Rslib 项目的 Rsbuild 配置和 Rspack 配置 + +Options: + -c --config 指定配置文件路径,可以为相对路径或绝对路径 + -r --root 指定项目根目录,可以是绝对路径或者相对于 cwd 的路径 + --env-mode 指定 env 模式来加载 `.env.[mode]` 文件 + --env-dir 指定目录来加载 `.env` 文件 + --lib 检查指定的库(可以重复) + --output 指定检查内容输出路径(默认:".rsbuild") + --verbose 在输出中显示完整的函数定义 + -h, --help 显示命令帮助 +``` + +当你在项目根目录下执行命令 `npx rsbuild inspect` 后,会在项目的 `dist/.rsbuild` 目录生成以下文件: + +- `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。 +- `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。 + +```text +➜ npx rslib inspect + +Inspect config succeed, open following files to view the content: + + - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs + - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs +``` + +### 完整内容 + +默认情况下,inspect 命令会省略配置对象中的函数内容,你可以添加 `--verbose` 选项来输出函数的完整内容: + +```bash +rslib inspect --verbose +``` + +### 多种输出格式 + +如果当前项目同时有多种输出格式,比如 ESM 产物和 CJS 产物,那么会在 `dist/.rsbuild` 目录生成多份 Rspack 配置文件。 + +```text +➜ npx rslib inspect + +Inspect config succeed, open following files to view the content: + + - Rsbuild Config (esm): /project/dist/.rsbuild/rsbuild.config.esm.mjs + - Rsbuild Config (cjs): /project/dist/.rsbuild/rsbuild.config.cjs.mjs + - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs + - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs +``` + +## rslib mf dev + +`rslib mf dev` 命令用于为 [Module Federation](/guide/advanced/module-federation) 格式的库启用 Rsbuild 开发服务器。 + +这允许你在 host 应用中访问和调试 mf 格式的模块。 + +```text +Usage: rslib mf [options] + +为 Module Federation 格式的库启用 Rsbuild 开发服务器。 + +Options: + -c --config 指定配置文件路径,可以为相对路径或绝对路径 + -r --root 指定项目根目录,可以是绝对路径或者相对于 cwd 的路径 + --env-mode 指定 env 模式来加载 `.env.[mode]` 文件 + --env-dir 指定目录来加载 `.env` 文件 + -h, --help 显示命令帮助 +``` + +## 公共选项 + +### 过滤器 + +Rslib 提供了 `--lib` 选项来为指定的库运行命令。 + +```bash +# 仅构建 id 为 `esm` 的库 +npx rslib build --lib esm +``` + +`--lib` 选项可以重复使用来指定多个库。 + +```bash +# 构建 id 为 `esm` 和 `cjs` 的库 +npx rslib build --lib esm --lib cjs +``` + +> 请查看 [lib.id](/config/lib/id) 了解如何获取或设置库的 ID。