Skip to content

docs: improve CLI doc structure and add common flags section #4485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chenjiahan merged 1 commit into from
Feb 5, 2025
Merged

docs: improve CLI doc structure and add common flags section #4485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion website/docs/en/guide/advanced/environments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ export default {
};
```

## Specify environment build
## Build specified environment

By default, Rsbuild will build all environments in the Rsbuild configuration when you execute `rsbuild dev` or `rsbuild build`. You can build only the specified environment via `--environment <name>`.

Expand Down
60 changes: 21 additions & 39 deletions website/docs/en/guide/basic/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Rsbuild comes with a lightweight CLI that includes commands such as [rsbuild dev](#rsbuild-dev) and [rsbuild build](#rsbuild-build).

## rsbuild -h
## All commands

To view all available CLI commands, run the following command in the project directory:

Expand All @@ -13,20 +13,30 @@ npx rsbuild -h
The output is shown below:

```text
Usage: rsbuild <command> [options]

Options:
-V, --version output the version number
-h, --help display help for command
Usage:
$ rsbuild <command> [options]

Commands:
dev [options] starting the dev server
build [options] build the app for production
preview [options] preview the production build locally
inspect [options] inspect the Rspack and Rsbuild configs
help [command] display help for command
dev starting the dev server
build build the app for production
preview preview the production build locally
inspect inspect the Rspack and Rsbuild configs
```

## Common flags

Rsbuild CLI provides several common flags that can be used with all commands:

| Flag | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --config <config>` | Specify the configuration file, can be a relative or absolute path, see [Specify config file](/guide/basic/configure-rsbuild#specify-config-file) |
| `-r, --root <root>` | Specify the project root directory |
| `-m, --mode <mode>` | Specify the build mode (`development`, `production` or `none`), see [mode](/config/mode) |
| `--env-mode <mode>` | Specify the env mode to load the `.env.[mode]` file, see [Env mode](/guide/advanced/env-vars#env-mode) |
| `--env-dir <dir>` | Specify the directory to load `.env` files, see [Env directory](/guide/advanced/env-vars#env-directory) |
| `--environment <name>` | Specify the name of environment to build, see [Build specified environment](/guide/advanced/environments#build-specified-environment) |
| `-h, --help` | Display help for command |

## rsbuild dev

The `rsbuild dev` command is used to start a local dev server and compile the source code for development.
Expand All @@ -35,16 +45,9 @@ The `rsbuild dev` command is used to start a local dev server and compile the so
Usage: rsbuild dev [options]

Options:
-c --config <config> specify the configuration file, can be a relative or absolute path
-r --root <root> specify the project root directory, can be an absolute path or a path relative to cwd
-m --mode <mode> specify the build mode, can be `development`, `production` or `none`
-o, --open [url] open the page in browser on startup
--port <port> specify a port number for Rsbuild Server to listen
--host <host> specify the host that the Rsbuild Server listens to
--env-mode <mode> specify the env mode to load the `.env.[mode]` file
--env-dir <dir> specify the directory to load `.env` files
--environment <name> specify the name of environment to build
-h, --help display help for command
```

### Opening page
Expand Down Expand Up @@ -79,14 +82,7 @@ The `rsbuild build` command will build the outputs for production in the `dist/`
Usage: rsbuild build [options]

Options:
-c --config <config> specify the configuration file, can be a relative or absolute path
-r --root <root> specify the project root directory, can be an absolute path or a path relative to cwd
-m --mode <mode> specify the build mode, can be `development`, `production` or `none`
-w --watch turn on watch mode, watch for changes and rebuild
--env-mode <mode> specify the env mode to load the `.env.[mode]` file
--env-dir <dir> specify the directory to load `.env` files
--environment <name> specify the name of environment to build
-h, --help display help for command
```

## rsbuild preview
Expand All @@ -97,16 +93,9 @@ The `rsbuild preview` command is used to preview the production build outputs lo
Usage: rsbuild preview [options]

Options:
-c --config <config> specify the configuration file, can be a relative or absolute path
-r --root <root> specify the project root directory, can be an absolute path or a path relative to cwd
-m --mode <mode> specify the build mode, can be `development`, `production` or `none`
-o, --open [url] open the page in browser on startup
--port <port> specify a port number for Rsbuild Server to listen
--host <host> specify the host that the Rsbuild Server listens to
--env-mode <mode> specify the env mode to load the `.env.[mode]` file
--env-dir <dir> specify the directory to load `.env` files
--environment <name> specify the name of environment to build
-h, --help display help for command
```

:::tip
Expand All @@ -121,15 +110,8 @@ The `rsbuild inspect` command is used to view the Rsbuild config and Rspack conf
Usage: rsbuild inspect [options]

Options:
-c --config <config> specify the configuration file, can be a relative or absolute path
-r --root <root> specify the project root directory, can be an absolute path or a path relative to cwd
-m --mode <mode> specify the build mode, can be `development`, `production` or `none`
--output <output> specify the path to output in the dist (default: ".rsbuild")
--verbose show the full function in the result
--env-mode <mode> specify the env mode to load the `.env.[mode]` file
--env-dir <dir> specify the directory to load `.env` files
--environment <name> specify the name of environment to build
-h, --help show command help
```

When you run the command `npx rsbuild inspect` in the project root directory, the following files will be generated in the `dist/.rsbuild` directory of the project:
Expand Down
2 changes: 1 addition & 1 deletion website/docs/zh/guide/advanced/environments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ export default {
};
```

## 仅构建指定环境
## 构建指定环境

默认情况下，当你执行 `rsbuild dev` 或 `rsbuild build` 时，Rsbuild 会构建所有 Rsbuild 配置中的环境。你可以通过 `--environment <name>` 仅构建指定环境。

Expand Down
60 changes: 21 additions & 39 deletions website/docs/zh/guide/basic/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Rsbuild 内置了一个轻量的命令行工具，包含 [rsbuild dev](#rsbuild-dev)、[rsbuild build](#rsbuild-build) 等命令。

## rsbuild -h
## 查看所有命令

如果你需要查看所有可用的 CLI 命令，请在项目目录中运行以下命令：

Expand All @@ -13,20 +13,30 @@ npx rsbuild -h
输出如下：

```text
Usage: rsbuild <command> [options]

Options:
-V, --version 显示版本号
-h, --help 显示命令帮助
Usage:
$ rsbuild <command> [options]

Commands:
dev [options] 启动开发服务器
build [options] 构建生产环境产物
preview [options] 本地预览生产环境产物
inspect [options] 检查 Rspack 和 Rsbuild 配置
help [command] 显示命令帮助
dev starting the dev server
build build the app for production
preview preview the production build locally
inspect inspect the Rspack and Rsbuild configs
```

## 公共选项

Rsbuild CLI 提供了一些公共选项，可以用于所有命令：

| 选项 | 描述 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `-c, --config <config>` | 指定配置文件路径，可以为相对路径或绝对路径，详见 [指定配置文件](/guide/basic/configure-rsbuild#指定配置文件) |
| `-r, --root <root>` | 指定项目根目录，可以是绝对路径或者相对于 cwd 的路径 |
| `-m, --mode <mode>` | 指定构建模式，可以是 `development`，`production` 或 `none`，详见 [mode](/config/mode) |
| `--env-mode <mode>` | 指定 env 模式来加载 `.env.[mode]` 文件，详见 [Env 模式](/guide/advanced/env-vars#env-模式) |
| `--env-dir <dir>` | 指定目录来加载 `.env` 文件，详见 [Env 目录](/guide/advanced/env-vars#env-目录) |
| `--environment <name>` | 指定需要构建的 environment 名称，详见 [构建指定环境](/guide/advanced/environments#构建指定环境) |
| `-h, --help` | 显示命令帮助 |

## rsbuild dev

`rsbuild dev` 命令用于启动一个本地开发服务器，对源代码进行开发模式编译。
Expand All @@ -35,16 +45,9 @@ Commands:
Usage: rsbuild dev [options]

Options:
-c --config <config> 指定配置文件路径，可以为相对路径或绝对路径
-r --root <root> 指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
-m --mode <mode> 指定构建模式，可以是 `development`，`production` 或 `none`
-o, --open [url] 启动时是否在浏览器中打开页面
--port <port> 设置 Rsbuild Server 监听的端口号
--host <host> 指定 Rsbuild Server 启动时监听的 host
--env-mode <mode> 指定 env 模式来加载 `.env.[mode]` 文件
--env-dir <dir> 指定目录来加载 `.env` 文件
--environment <name> 指定需要构建的 environment 名称
-h, --help 显示命令帮助
```

### 打开页面
Expand Down Expand Up @@ -79,14 +82,7 @@ rsbuild dev -o
Usage: rsbuild build [options]

Options:
-c --config <config> 指定配置文件路径，可以为相对路径或绝对路径
-r --root <root> 指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
-m --mode <mode> 指定构建模式，可以是 `development`，`production` 或 `none`
-w --watch 开启 watch 模式, 监听文件变更并重新构建
--env-mode <mode> 指定 env 模式来加载 `.env.[mode]` 文件
--env-dir <dir> 指定目录来加载 `.env` 文件
--environment <name> 指定需要构建的 environment 名称
-h, --help 显示命令帮助
```

## rsbuild preview
Expand All @@ -97,16 +93,9 @@ Options:
Usage: rsbuild preview [options]

Options:
-c --config <config> 指定配置文件路径，可以为相对路径或绝对路径
-r --root <root> 指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
-m --mode <mode> 指定构建模式，可以是 `development`，`production` 或 `none`
-o, --open [url] 启动时是否在浏览器中打开页面
--port <port> 设置 Rsbuild Server 监听的端口号
--host <host> 指定 Rsbuild Server 启动时监听的 host
--env-mode <mode> 指定 env 模式来加载 `.env.[mode]` 文件
--env-dir <dir> 指定目录来加载 `.env` 文件
--environment <name> 指定需要构建的 environment 名称
-h, --help 显示命令帮助
```

:::tip
Expand All @@ -121,15 +110,8 @@ preview 命令仅用于本地预览，请勿将它用于生产服务器，因为
Usage: rsbuild inspect [options]

Options:
-c --config <config> 指定配置文件路径，可以为相对路径或绝对路径
-r --root <root> 指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
-m --mode <mode> 指定构建模式，可以是 `development`，`production` 或 `none`
--output <output> 指定在 dist 目录下输出的路径 (default: ".rsbuild")
--verbose 在结果中展示函数的完整内容
--env-mode <mode> 指定 env 模式来加载 `.env.[mode]` 文件
--env-dir <dir> 指定目录来加载 `.env` 文件
--environment <name> 指定需要构建的 environment 名称
-h, --help 显示命令帮助
```

当你在项目根目录下执行命令 `npx rsbuild inspect` 后，会在项目的 `dist/.rsbuild` 目录生成以下文件：
Expand Down