Skip to content

Commit 3680eb5

Browse files
chenjiahanchenjiahan
authored
docs: add monorepo guide (#79)
1 parent 2a9e683 commit 3680eb5

4 files changed

Lines changed: 354 additions & 0 deletions

File tree

‎website/docs/en/guide/_meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@
2222
"type": "section-header",
2323
"label": "Practices"
2424
},
25+
{
26+
"type": "file",
27+
"name": "monorepo",
28+
"label": "Monorepo"
29+
},
2530
{
2631
"type": "file",
2732
"name": "testing",

‎website/docs/en/guide/monorepo.mdx‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Monorepo
2+
3+
This guide explains how to use Rstack CLI in a monorepo, including how it works with task orchestrators such as [Turborepo](https://turborepo.com/docs) and [Nx](https://nx.dev/docs/getting-started/intro).
4+
5+
It covers managing Rstack dependencies, configuring lint and staged-file tasks at the root, and defining separate configurations for web applications and libraries.
6+
7+
## Project structure
8+
9+
The recommended setup has two levels:
10+
11+
- The root manages the shared Rstack version, lint rules, and staged-file tasks.
12+
- Each application or library has its own [Rstack configuration](./configuration) for build, test, or documentation configuration.
13+
14+
```text
15+
.
16+
├── package.json
17+
├── rstack.config.ts
18+
├── apps/
19+
│ └── web/
20+
│ ├── package.json
21+
│ └── rstack.config.ts
22+
└── packages/
23+
└── utils/
24+
├── package.json
25+
└── rstack.config.ts
26+
```
27+
28+
This structure keeps the Rstack version in one place while keeping build and test configuration close to the project that uses it.
29+
30+
## Rstack dependency management
31+
32+
Declare Rstack in the root `package.json` so projects use one version by default. See [Quick start](./quick-start#install-rstack) for installation instructions.
33+
34+
If a project needs a different Rstack version from the root, declare that version as a dependency of the project.
35+
36+
Project-specific dependencies, such as Rsbuild plugins and testing libraries, should be declared in the projects that use them.
37+
38+
## Root configuration
39+
40+
Use [`define.lint()`](./configuration#define-lint) and [`define.staged()`](./configuration#define-staged) in the root `rstack.config.ts` for checks that apply to the entire repository:
41+
42+
```ts title="rstack.config.ts"
43+
import { define } from 'rstack';
44+
45+
define.lint(async () => {
46+
const { js, ts } = await import('rstack/lint');
47+
48+
return [js.configs.recommended, ts.configs.recommended];
49+
});
50+
51+
define.staged({
52+
'*.{js,jsx,ts,tsx,mjs,cjs}': 'rs lint',
53+
});
54+
```
55+
56+
Expose these tasks through scripts in the root `package.json`:
57+
58+
```json title="package.json"
59+
{
60+
"private": true,
61+
"scripts": {
62+
"lint": "rs lint",
63+
"staged": "rs staged"
64+
}
65+
}
66+
```
67+
68+
Unless the root is itself a buildable project, you do not need to add application or library build configuration to the root config.
69+
70+
### Project-specific lint rules
71+
72+
If some projects need different lint rules, use [`files`](https://rslint.rs/config/#files) patterns to match the relevant files. These paths are resolved from the repository root:
73+
74+
```ts title="rstack.config.ts"
75+
import { define } from 'rstack';
76+
77+
define.lint(async () => {
78+
const { js, ts } = await import('rstack/lint');
79+
80+
return [
81+
js.configs.recommended,
82+
ts.configs.recommended,
83+
{
84+
files: ['apps/web/**/*.{ts,tsx}'],
85+
rules: {
86+
'@typescript-eslint/no-explicit-any': 'off',
87+
},
88+
},
89+
];
90+
});
91+
```
92+
93+
## Project configuration
94+
95+
For each project that uses [Rstack commands](./quick-start#cli-commands), create a [`rstack.config.ts`](./configuration#configuration-file) and register only the configuration that project needs.
96+
97+
Rstack loads the configuration from the current working directory. It does not merge a project's configuration with the root configuration.
98+
99+
### Web application
100+
101+
A web application usually needs application build configuration and optional test configuration:
102+
103+
```ts title="apps/web/rstack.config.ts"
104+
import { define } from 'rstack';
105+
106+
define.app(async () => {
107+
const { pluginReact } = await import('@rsbuild/plugin-react');
108+
109+
return {
110+
plugins: [pluginReact()],
111+
};
112+
});
113+
114+
define.test({
115+
globals: true,
116+
});
117+
```
118+
119+
Add scripts to the application's `package.json`, for example:
120+
121+
```json title="apps/web/package.json"
122+
{
123+
"name": "@example/web",
124+
"scripts": {
125+
"dev": "rs dev",
126+
"build": "rs build",
127+
"preview": "rs preview",
128+
"test": "rs test"
129+
}
130+
}
131+
```
132+
133+
### Library project
134+
135+
A library can define its build, test, and documentation configuration in one file:
136+
137+
```ts title="packages/utils/rstack.config.ts"
138+
import { define } from 'rstack';
139+
140+
define.lib({
141+
lib: [
142+
{
143+
format: 'esm',
144+
dts: true,
145+
},
146+
],
147+
});
148+
149+
define.test({
150+
testEnvironment: 'node',
151+
});
152+
153+
// Configure this only when the library needs a documentation site.
154+
define.doc({
155+
root: 'docs',
156+
title: 'Utils',
157+
});
158+
```
159+
160+
Add scripts to the library's `package.json`, for example:
161+
162+
```json title="packages/utils/package.json"
163+
{
164+
"name": "@example/utils",
165+
"scripts": {
166+
"build": "rs lib",
167+
"dev": "rs lib -w",
168+
"test": "rs test",
169+
"doc": "rs doc"
170+
}
171+
}
172+
```

‎website/docs/zh/guide/_meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@
2222
"type": "section-header",
2323
"label": "实践"
2424
},
25+
{
26+
"type": "file",
27+
"name": "monorepo",
28+
"label": "Monorepo"
29+
},
2530
{
2631
"type": "file",
2732
"name": "testing",

‎website/docs/zh/guide/monorepo.mdx‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Monorepo
2+
3+
本指南介绍如何在 Monorepo 中使用 Rstack CLI，以及如何让它与 [Turborepo](https://turborepo.com/docs)、[Nx](https://nx.dev/docs/getting-started/intro) 等任务编排工具协同工作。
4+
5+
主要内容包括管理 Rstack 依赖、在根目录统一配置代码检查和暂存文件任务，以及为 Web 应用和库项目定义独立配置。
6+
7+
## 目录结构 \{#project-structure}
8+
9+
推荐使用两层配置：
10+
11+
- 根目录统一管理 Rstack 版本、lint 规则和暂存文件任务。
12+
- 每个应用或库使用自己的 [Rstack 配置](./configuration)，定义构建、测试或文档配置。
13+
14+
```text
15+
.
16+
├── package.json
17+
├── rstack.config.ts
18+
├── apps/
19+
│ └── web/
20+
│ ├── package.json
21+
│ └── rstack.config.ts
22+
└── packages/
23+
└── utils/
24+
├── package.json
25+
└── rstack.config.ts
26+
```
27+
28+
这种结构既能统一 Rstack 版本，也能让构建和测试配置靠近实际使用它们的项目。
29+
30+
## Rstack 依赖管理 \{#rstack-dependency-management}
31+
32+
在根目录的 `package.json` 中声明 Rstack，让各个项目默认使用同一个版本。安装方法请参考[快速上手](./quick-start#install-rstack)。
33+
34+
如果子项目需要使用与根目录不同版本的 `rstack`，可以在该项目中单独声明对应版本的 `rstack` 依赖。
35+
36+
Rsbuild 插件、测试库等项目专属依赖，建议定义在实际使用它们的子项目中。
37+
38+
## 根配置 \{#root-configuration}
39+
40+
在根目录的 `rstack.config.ts` 中使用 [`define.lint()`](./configuration#define-lint) 和 [`define.staged()`](./configuration#define-staged) 配置适用于整个仓库的检查：
41+
42+
```ts title="rstack.config.ts"
43+
import { define } from 'rstack';
44+
45+
define.lint(async () => {
46+
const { js, ts } = await import('rstack/lint');
47+
48+
return [js.configs.recommended, ts.configs.recommended];
49+
});
50+
51+
define.staged({
52+
'*.{js,jsx,ts,tsx,mjs,cjs}': 'rs lint',
53+
});
54+
```
55+
56+
在根目录的 `package.json` 中提供对应脚本：
57+
58+
```json title="package.json"
59+
{
60+
"private": true,
61+
"scripts": {
62+
"lint": "rs lint",
63+
"staged": "rs staged"
64+
}
65+
}
66+
```
67+
68+
除非根目录本身也是一个需要构建的项目，否则不需要在根配置中添加应用或库的构建配置。
69+
70+
### 项目级 lint 规则 \{#project-specific-lint-rules}
71+
72+
如果部分项目需要不同的 lint 规则，可以通过 [`files`](https://rslint.rs/config/#files) 匹配对应文件。这里的路径从仓库根目录开始计算：
73+
74+
```ts title="rstack.config.ts"
75+
import { define } from 'rstack';
76+
77+
define.lint(async () => {
78+
const { js, ts } = await import('rstack/lint');
79+
80+
return [
81+
js.configs.recommended,
82+
ts.configs.recommended,
83+
{
84+
files: ['apps/web/**/*.{ts,tsx}'],
85+
rules: {
86+
'@typescript-eslint/no-explicit-any': 'off',
87+
},
88+
},
89+
];
90+
});
91+
```
92+
93+
## 子项目配置 \{#project-configuration}
94+
95+
为每个使用 [Rstack 命令](./quick-start#cli-commands)的子项目创建 [`rstack.config.ts`](./configuration#configuration-file)，并且只配置该项目需要的功能。
96+
97+
Rstack 会加载当前工作目录中的配置，不会将子项目配置与根配置自动合并。
98+
99+
### Web 应用 \{#web-application}
100+
101+
Web 应用通常需要应用构建配置和可选的测试配置：
102+
103+
```ts title="apps/web/rstack.config.ts"
104+
import { define } from 'rstack';
105+
106+
define.app(async () => {
107+
const { pluginReact } = await import('@rsbuild/plugin-react');
108+
109+
return {
110+
plugins: [pluginReact()],
111+
};
112+
});
113+
114+
define.test({
115+
globals: true,
116+
});
117+
```
118+
119+
在应用的 `package.json` 中添加脚本，例如：
120+
121+
```json title="apps/web/package.json"
122+
{
123+
"name": "@example/web",
124+
"scripts": {
125+
"dev": "rs dev",
126+
"build": "rs build",
127+
"preview": "rs preview",
128+
"test": "rs test"
129+
}
130+
}
131+
```
132+
133+
### 库项目 \{#library-project}
134+
135+
库可以在一份配置中定义构建、测试和文档：
136+
137+
```ts title="packages/utils/rstack.config.ts"
138+
import { define } from 'rstack';
139+
140+
define.lib({
141+
lib: [
142+
{
143+
format: 'esm',
144+
dts: true,
145+
},
146+
],
147+
});
148+
149+
define.test({
150+
testEnvironment: 'node',
151+
});
152+
153+
// 仅当库需要文档站点时配置。
154+
define.doc({
155+
root: 'docs',
156+
title: 'Utils',
157+
});
158+
```
159+
160+
在库的 `package.json` 中添加脚本，例如：
161+
162+
```json title="packages/utils/package.json"
163+
{
164+
"name": "@example/utils",
165+
"scripts": {
166+
"build": "rs lib",
167+
"dev": "rs lib -w",
168+
"test": "rs test",
169+
"doc": "rs doc"
170+
}
171+
}
172+
```

0 commit comments

Comments
 (0)