Skip to content

Commit 4e90bc8

Browse files
nyqykknyqykk
authored
docs: add doc (#4)
* docs: add doc * feat: add stream log * docs: add zh link * docs: add common qa
1 parent fc53ac3 commit 4e90bc8

File tree

6 files changed

+437
-50
lines changed

6 files changed

+437
-50
lines changed

‎README.md‎

Lines changed: 181 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,181 @@
1-
# rsbuild-plugin-workspace-dev
1+
# rsbuild-plugin-workspace-dev
2+
3+
Start monorepo sub-projects in topological order.
4+
5+
`rsbuild-plugin-workspace-dev` is designed for monorepo development. It computes the dependency graph starting from the current project and starts sub-projects in topological order.
6+
7+
<p>
8+
<a href="https://npmjs.com/package/rsbuild-plugin-workspace-dev">
9+
<img src="https://img.shields.io/npm/v/rsbuild-plugin-workspace-dev?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
10+
</a>
11+
<img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
12+
</p>
13+
14+
English | [简体中文](./README.zh-CN.md)
15+
16+
## Usage
17+
18+
Install:
19+
20+
```bash
21+
pnpm add rsbuild-plugin-workspace-dev -D
22+
```
23+
24+
Register the plugin in `rsbuild.config.ts`:
25+
26+
```ts
27+
// rsbuild.config.ts
28+
import { pluginWorkspaceDev } from "rsbuild-plugin-workspace-dev";
29+
30+
export default {
31+
plugins: [pluginWorkspaceDev()],
32+
};
33+
```
34+
35+
## Use Cases
36+
37+
In a monorepo, one project may depend on multiple sub-projects, and those sub-projects can also depend on each other.
38+
39+
For example, the monorepo contains an app and several lib packages:
40+
41+
```ts
42+
monorepo
43+
├── app
44+
└── lib1
45+
└── lib2
46+
└── lib3
47+
```
48+
49+
Here, app is built with Rsbuild, and lib is built with Rslib. The app depends on lib1 and lib2:
50+
51+
```json
52+
{
53+
"name": "app",
54+
"dependencies": {
55+
"lib1": "workspace:*",
56+
"lib2": "workspace:*"
57+
}
58+
}
59+
```
60+
61+
`lib2` depends on `lib3`:
62+
63+
```json
64+
{
65+
"name": "lib2",
66+
"dependencies": {
67+
"lib3": "workspace:*"
68+
}
69+
}
70+
```
71+
72+
When you run `pnpm dev` under app, sub-projects start in topological order: first lib1 and lib3, then lib2, and finally app. Starting a lib refers to running its dev command, for example:
73+
74+
```json
75+
{
76+
"scripts": {
77+
"dev": "rslib build --watch"
78+
}
79+
}
80+
```
81+
82+
Whether a sub-project has finished starting is determined by matching sub-project logs. By default, logs from Rslib and tsup sub-projects are recognized. You can also provide a custom match function to determine when a sub-project is ready.
83+
84+
## Options
85+
86+
### projectConfig
87+
Configure how sub-projects are started and define custom log matching logic.
88+
89+
- Type:
90+
```
91+
interface ProjectConfig {
92+
/**
93+
* Custom sub-project start command. Default is `dev` (runs `npm run dev`).
94+
*/
95+
command?: string;
96+
/**
97+
* Custom logic to detect when a sub-project has started.
98+
* By default, logs from `Rsbuild` and `tsup` are supported.
99+
*/
100+
match?: (stdout: string) => boolean;
101+
/**
102+
* Whether to skip starting the current sub-project. Default is `false`.
103+
* Useful for sub-projects that do not need to be started.
104+
*/
105+
skip?: boolean;
106+
}
107+
```
108+
109+
### ignoreSelf
110+
111+
- Type: `boolean`
112+
- Default: `true`
113+
114+
Whether to ignore starting the current project. The default is `true`. In most cases, you start the current project manually, so the plugin does not interfere.
115+
116+
Consider a scenario where docs and lib are in the same project, and docs needs to debug the output of lib. In this case, you want to run `pnpm doc` for the docs, while lib should run `pnpm dev`. After configuring this option in your Rspress config, starting `pnpm doc` will automatically run `pnpm dev` to start the lib sub-project.
117+
118+
```
119+
├── docs
120+
│ └── index.mdx
121+
├── package.json
122+
├── src
123+
│ └── Button.tsx
124+
├── rslib.config.ts
125+
├── rspress.config.ts
126+
```
127+
128+
```
129+
"scripts": {
130+
"dev": "rslib build --watch",
131+
"doc": "rspress dev"
132+
},
133+
```
134+
135+
### cwd
136+
137+
- Type: `string`
138+
- Default: `process.cwd()`
139+
140+
Set the current working directory. The default is the current project directory; usually no configuration is needed.
141+
142+
### workspaceFileDir
143+
144+
- Type: `string`
145+
- Default: `process.cwd()`
146+
147+
Set the directory where the workspace file resides. The default is the current project directory; usually no configuration is needed.
148+
149+
## Frequently Asked Questions
150+
151+
### Project startup stuck
152+
Stuck may be due to slow sub-project builds, etc. The lack of log output is because, by default, sub-project logs are output all at once after startup (to avoid interleaving sub-project logs). You can enable debug mode by adding an environment variable, which will allow sub-project logs to be output in real time.
153+
154+
```
155+
DEBUG=rsbuild pnpm dev
156+
```
157+
158+
### Some projects don't need to start
159+
160+
If some sub-projects don't need to start, simply configure `skip: true` for the specified project in `rsbuild.config.ts`.
161+
162+
```ts
163+
// rsbuild.config.ts
164+
import { pluginWorkspaceDev } from "rsbuild-plugin-workspace-dev";
165+
166+
export default {
167+
plugins: [
168+
pluginWorkspaceDev({
169+
projectConfig: {
170+
lib1: {
171+
skip: true,
172+
},
173+
},
174+
}),
175+
],
176+
};
177+
```
178+
179+
## License
180+
181+
[MIT](./LICENSE).

‎README.zh-CN.md‎

Lines changed: 172 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,172 @@
1-
# @rsbuild/watch-dev-plugin
1+
# rsbuild-plugin-workspace-dev
2+
3+
提供按拓扑顺序启动 monorepo 子项目的能力。
4+
5+
`rsbuild-plugin-workspace-dev` 用于 monorepo 开发场景，它支持从当前项目开始计算依赖关系生成拓扑图，按拓扑顺序启动子项目。
6+
7+
<p>
8+
<a href="https://npmjs.com/package/rsbuild-plugin-workspace-dev">
9+
<img src="https://img.shields.io/npm/v/rsbuild-plugin-workspace-dev?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
10+
</a>
11+
<img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
12+
</p>
13+
14+
## 使用
15+
16+
安装：
17+
18+
```bash
19+
pnpm add rsbuild-plugin-workspace-dev -D
20+
```
21+
22+
在 `rsbuild.config.ts` 里注册插件:
23+
24+
```ts
25+
// rsbuild.config.ts
26+
import { pluginWorkspaceDev } from "rsbuild-plugin-workspace-dev";
27+
28+
export default {
29+
plugins: [pluginWorkspaceDev()],
30+
};
31+
```
32+
33+
## 使用场景
34+
35+
在 monorepo 中，一个项目可能依赖多个子项目，而子项目之间也可能存在依赖关系。
36+
37+
比如 monorepo 中包含了一个 app 应用和多个 lib 包：
38+
39+
```ts
40+
monorepo
41+
├── app
42+
└── lib1
43+
└── lib2
44+
└── lib3
45+
```
46+
47+
其中，app 是基于 Rsbuild 构建的, lib 是基于 Rslib 构建的。app 依赖了 lib1 和 lib2：
48+
49+
```json
50+
{
51+
"name": "app",
52+
"dependencies": {
53+
"lib1": "workspace:*",
54+
"lib2": "workspace:*"
55+
}
56+
}
57+
```
58+
59+
lib2 依赖了 lib3：
60+
61+
```json
62+
{
63+
"name": "lib2",
64+
"dependencies": {
65+
"lib3": "workspace:*"
66+
}
67+
}
68+
```
69+
此时在 app 下执行 `pnpm dev` 后，会按照拓扑顺序先启动 lib1 和 lib3，再启动 lib2，最后启动 app。此处启动 lib 指的是执行 lib 的 dev 命令
70+
```json
71+
{
72+
"scripts": {
73+
"dev": "rslib build --watch"
74+
}
75+
}
76+
```
77+
识别子项目是否启动完成是通过匹配子项目日志实现的，默认支持匹配 Rslib、tsup 子项目，同时支持手动配置 match 匹配日志。
78+
79+
## 选项
80+
81+
### projectConfig
82+
用于子项目的启动项配置和自定义日志匹配逻辑。
83+
84+
- **类型：**:
85+
```
86+
interface ProjectConfig {
87+
/**
88+
* 自定义子项目启动命令，默认值为 `dev`, 即执行 `npm run dev`。
89+
*/
90+
command?: string;
91+
/**
92+
* 自定义子项目启动完成匹配逻辑，默认支持 `Rsbuild`、`tsup` 子项目的日志匹配逻辑。
93+
*/
94+
match?: (stdout: string) => boolean;
95+
/**
96+
* 是否跳过当前子项目的启动，默认值为 `false`，通常用于跳过一些不需要启动的子项目。
97+
*/
98+
skip?: boolean;
99+
}
100+
```
101+
102+
### ignoreSelf
103+
104+
- **类型：** `boolean`
105+
- **默认值：** `true`
106+
-
107+
是否忽略当前项目的启动，默认值为 `true`。一般无需手动配置，当前项目通常由用户手动执行 dev 启动，无需插件干预。
108+
109+
考虑如下场景，docs 和 lib 是在同一个项目中，而 docs 需要调试 lib 的产物，此时需要启动 `pnpm doc` 命令，而 lib 则需要启动 `pnpm dev` 命令，配置该选项到 rspress 配置中后，启动 `pnpm doc` 时会自动执行 `pnpm dev` 命令，用于启动 lib 子项目。
110+
```
111+
├── docs
112+
│ └── index.mdx
113+
├── package.json
114+
├── src
115+
│ └── Button.tsx
116+
├── rslib.config.ts
117+
├── rspress.config.ts
118+
```
119+
```
120+
"scripts": {
121+
"dev": "rslib build --watch",
122+
"doc": "rspress dev"
123+
},
124+
```
125+
126+
### cwd
127+
128+
- **类型：** `string`
129+
- **默认值：** `process.cwd()`
130+
131+
用于配置当前工作目录，默认值为当前项目目录，一般无需配置。
132+
133+
### workspaceFileDir
134+
135+
- **类型：** `string`
136+
- **默认值：** `process.cwd()`
137+
138+
用于配置 workspace 文件目录，默认值为当前项目目录，一般无需配置。
139+
140+
141+
## 常见问题
142+
143+
### 启动项目时卡住
144+
卡住可能是因为子项目构建过慢等原因，没有日志输出是因为默认情况下子项目日志是启动完成后一次性输出的（为了避免子项目日志混和在一起交错输出），可以通过添加环境变量来开启调试模式，这会让子项目的日志实时输出。
145+
```
146+
DEBUG=rsbuild pnpm dev
147+
```
148+
149+
### 某些项目无需启动
150+
如果某些子项目不需要启动，只需要在 `rsbuild.config.ts` 中给指定项目配置 `skip: true` 即可。
151+
152+
```ts
153+
// rsbuild.config.ts
154+
import { pluginWorkspaceDev } from "rsbuild-plugin-workspace-dev";
155+
156+
export default {
157+
plugins: [
158+
pluginWorkspaceDev({
159+
projectConfig: {
160+
lib1: {
161+
skip: true,
162+
},
163+
},
164+
}),
165+
],
166+
};
167+
```
168+
169+
170+
## License
171+
172+
[MIT](./LICENSE).

‎src/constant.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
export const PACKAGE_JSON = 'package.json';
2-
export const RSLIB_READY_MESSAGE = 'build complete, watching for changes';
32
export const DEBUG_LOG_TITLE = '[Rsbuild Workspace Dev Plugin]: ';
3+
4+
export const RSLIB_READY_MESSAGE = 'build complete, watching for changes';
5+
export const MODERN_MODULE_READY_MESSAGE = 'Watching for file changes';
6+
export const TSUP_READY_MESSAGE = 'Watching for changes in';

0 commit comments

Comments
 (0)