Skip to content

Commit 9f5aa35

Browse files
Timeless0911Timeless0911
authored
docs: optimize cli docs (#1013)
1 parent f4a2c10 commit 9f5aa35

File tree

2 files changed

+57
-289
lines changed

2 files changed

+57
-289
lines changed

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

Lines changed: 27 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Rslib comes with a lightweight CLI that includes commands such as [rslib build](#rslib-build) and [rslib inspect](#rslib-inspect).
44

5-
## rslib -h
5+
## All commands
66

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

@@ -12,52 +12,46 @@ npx rslib -h
1212

1313
The output is shown below:
1414

15-
```text
16-
Usage: rslib <command> [options]
17-
18-
Options:
19-
-V, --version output the version number
20-
-h, --help display help for command
15+
```bash
16+
Usage:
17+
$ rslib <command> [options]
2118

2219
Commands:
23-
build [options] build the library for production
24-
inspect [options] inspect the Rsbuild / Rspack configs of Rslib projects
25-
mf-dev [options] start Rsbuild dev server of Module Federation format
26-
help [command] display help for command
20+
build build the library for production
21+
inspect inspect the Rsbuild / Rspack configs of Rslib projects
22+
mf-dev start Rsbuild dev server of Module Federation format
2723
```
2824

25+
## Common flags
26+
27+
Rslib CLI provides several common flags that can be used with all commands:
28+
29+
| Flag | Description |
30+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
31+
| `-c, --config <config>` | Specify the configuration file, can be a relative or absolute path, see [Specify config file](/guide/basic/configure-rslib#specify-config-file) |
32+
| `--env-dir <dir>` | Specify the directory to load `.env` files, see [Rsbuild - Env directory](https://rsbuild.dev/guide/advanced/env-vars#env-directory) |
33+
| `--env-mode <mode>` | Specify the env mode to load the `.env.[mode]` file, see [Rsbuild - Env mode](https://rsbuild.dev/guide/advanced/env-vars#env-mode) |
34+
| `-h, --help` | Display help for command |
35+
| `--lib <id>` | Specify the library to run commands (repeatable, e.g. `--lib esm --lib cjs`), see [lib.id](/config/lib/id) to learn how to get or set the ID of the library |
36+
| `-r, --root <root>` | Specify the project root directory, can be an absolute path or a path relative to cwd |
37+
2938
## rslib build
3039

3140
The `rslib build` command will build the outputs for production in the `dist/` directory by default.
3241

33-
```text
34-
Usage: rslib build [options]
35-
36-
build the library for production
42+
```bash
43+
Usage:
44+
$ rslib build
3745

3846
Options:
39-
-c --config <config> specify the configuration file, can be a relative or absolute path
40-
-r --root <root> specify the project root directory, can be an absolute path or a path relative to cwd
41-
--env-mode <mode> specify the env mode to load the `.env.[mode]` file
42-
--env-dir <dir> specify the directory to load `.env` files
43-
--lib <id> specify the library (repeatable, e.g. --lib esm --lib cjs)
4447
-w --watch turn on watch mode, watch for changes and rebuild
45-
-h, --help display help for command
46-
```
47-
48-
### Watch mode
49-
50-
You can use `rslib build --watch` or `rslib build -w` to enable watch mode for watching for changes and rebuild.
51-
52-
```bash
53-
npx rslib build -w
5448
```
5549

5650
### Environment variables
5751

5852
Rslib supports injecting env variables or expressions into the code during build, which is helpful for distinguishing the running environment or replacing constants.
5953

60-
You can see more details in [Rsbuild - Environment Variables](https://rsbuild.dev/guide/advanced/env-vars).
54+
You can see more details in [Rsbuild - Environment variables](https://rsbuild.dev/guide/advanced/env-vars).
6155

6256
::: note
6357

@@ -66,93 +60,17 @@ You can see more details in [Rsbuild - Environment Variables](https://rsbuild.de
6660

6761
:::
6862

69-
#### Env mode
70-
71-
Rslib supports reading `.env.[mode]` and `.env.[mode].local` files. You can specify the env mode using the `--env-mode <mode>` flag.
72-
73-
For example, set the env mode as `test`:
74-
75-
```bash
76-
npx rslib build --env-mode test
77-
```
78-
79-
Rslib will then read the following files in sequence:
80-
81-
- `.env`
82-
- `.env.local`
83-
- `.env.test`
84-
- `.env.test.local`
85-
86-
:::tip
87-
88-
The `--env-mode` option takes precedence over `process.env.NODE_ENV`.
89-
90-
It is recommended to use `--env-mode` to set the env mode, and not to modify `process.env.NODE_ENV`.
91-
92-
:::
93-
94-
#### Env directory
95-
96-
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.
97-
98-
For example, to specify the env directory as `config`:
99-
100-
```bash
101-
npx rslib build --env-dir config
102-
```
103-
104-
In this case, Rslib will read the `./config/.env` and other env files.
105-
106-
##### Example
107-
108-
For example, create a `.env` file and add the following contents:
109-
110-
```shell title=".env"
111-
FOO=hello
112-
BAR=1
113-
```
114-
115-
Then in the `rslib.config.ts` file, you can access the above env variables using `import.meta.env.[name]` or `process.env.[name]`:
116-
117-
```ts title="rslib.config.ts"
118-
console.log(import.meta.env.FOO); // 'hello'
119-
console.log(import.meta.env.BAR); // '1'
120-
121-
console.log(process.env.FOO); // 'hello'
122-
console.log(process.env.BAR); // '1'
123-
```
124-
125-
Now, create a `.env.local` file and add the following contents:
126-
127-
```shell title=".env.local"
128-
BAR=2
129-
```
130-
131-
The value of `BAR` is overwritten to `'2'`:
132-
133-
```ts title="rslib.config.ts"
134-
console.log(import.meta.env.BAR); // '2'
135-
console.log(process.env.BAR); // '2'
136-
```
137-
13863
## rslib inspect
13964

14065
The `rslib inspect` command is used to view the Rsbuild config and Rspack config of the Rslib project.
14166

142-
```text
143-
Usage: rslib inspect [options]
144-
145-
inspect the Rsbuild / Rspack configs of Rslib projects
67+
```bash
68+
Usage:
69+
$ rslib inspect
14670

14771
Options:
148-
-c --config <config> specify the configuration file, can be a relative or absolute path
149-
-r --root <root> specify the project root directory, can be an absolute path or a path relative to cwd
150-
--env-mode <mode> specify the env mode to load the `.env.[mode]` file
151-
--env-dir <dir> specify the directory to load `.env` files
152-
--lib <id> specify the library (repeatable, e.g. --lib esm --lib cjs)
15372
--output <output> specify inspect content output path (default: ".rsbuild")
15473
--verbose show full function definitions in output
155-
-h, --help display help for command
15674
```
15775

15876
When you run the command `npx rslib inspect` in the project root directory, the following files will be generated in the `dist/.rsbuild` directory of the project:
@@ -197,37 +115,3 @@ Inspect config succeed, open following files to view the content:
197115
The `rslib mf-dev` command is utilized to start Rsbuild dev server for the [Module Federation](/guide/advanced/module-federation) format.
198116

199117
This enables you to develop and debug your mf format module within the host app.
200-
201-
```text
202-
Usage: rslib mf-dev [options]
203-
204-
start Rsbuild dev server of Module Federation format
205-
206-
Options:
207-
-c --config <config> specify the configuration file, can be a relative or absolute path
208-
-r --root <root> specify the project root directory, can be an absolute path or a path relative to cwd
209-
--env-mode <mode> specify the env mode to load the `.env.[mode]` file
210-
--env-dir <dir> specify the directory to load `.env` files
211-
--lib <id> specify the library (repeatable, e.g. --lib esm --lib cjs)
212-
-h, --help display help for command
213-
```
214-
215-
## Common options
216-
217-
### Filter libraries
218-
219-
Rslib provides the `--lib` option to run command for specified libraries.
220-
221-
```bash
222-
# Only build the library with id `esm`
223-
npx rslib build --lib esm
224-
```
225-
226-
The `--lib` option can be repeated to specify multiple libraries.
227-
228-
```bash
229-
# Build the libraries with id `esm` and `cjs`
230-
npx rslib build --lib esm --lib cjs
231-
```
232-
233-
> Check out the [lib.id](/config/lib/id) to learn how to get or set the library ID.

0 commit comments

Comments
 (0)