@icebreakers/monorepo-templates 1.0.4 → 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/package.json +11 -21
- package/package.json +4 -4
- package/templates/cli/package.json +1 -1
- package/templates/client/package.json +7 -7
- package/templates/client/worker-configuration.d.ts +8 -17
- package/templates/server/package.json +3 -3
- package/templates/server/worker-configuration.d.ts +8 -17
- package/templates/vitepress/.vitepress/config.ts +42 -5
- package/templates/vitepress/ai/index.md +33 -0
- package/templates/vitepress/ai/llms-txt.md +42 -0
- package/templates/vitepress/en/index.md +7 -7
- package/templates/vitepress/en/knowledge/monorepo.md +1 -1
- package/templates/vitepress/en/repoctl/adopt-existing.md +13 -11
- package/templates/vitepress/en/repoctl/aliases.md +3 -4
- package/templates/vitepress/en/repoctl/commands.md +12 -12
- package/templates/vitepress/en/repoctl/config.md +1 -1
- package/templates/vitepress/en/repoctl/getting-started.md +19 -19
- package/templates/vitepress/en/repoctl/index.md +10 -10
- package/templates/vitepress/en/repoctl/scenarios.md +6 -6
- package/templates/vitepress/en/repoctl/troubleshooting.md +2 -2
- package/templates/vitepress/en/repoctl/workflows.md +12 -12
- package/templates/vitepress/getting-started.md +3 -3
- package/templates/vitepress/index.md +11 -8
- package/templates/vitepress/knowledge/index.md +50 -0
- package/templates/vitepress/monorepo/commands.md +5 -5
- package/templates/vitepress/monorepo/index.md +14 -14
- package/templates/vitepress/monorepo/manage.md +21 -21
- package/templates/vitepress/monorepo/troubleshooting.md +1 -1
- package/templates/vitepress/package.json +2 -2
- package/templates/vitepress/repoctl/adopt-existing.md +22 -22
- package/templates/vitepress/repoctl/aliases.md +4 -5
- package/templates/vitepress/repoctl/checks.md +86 -0
- package/templates/vitepress/repoctl/commands.md +28 -14
- package/templates/vitepress/repoctl/config.md +10 -1
- package/templates/vitepress/repoctl/doctor.md +86 -0
- package/templates/vitepress/repoctl/execution-model.md +81 -0
- package/templates/vitepress/repoctl/getting-started.md +16 -16
- package/templates/vitepress/repoctl/index.md +40 -12
- package/templates/vitepress/repoctl/reports.md +94 -0
- package/templates/vitepress/repoctl/scenarios.md +6 -6
- package/templates/vitepress/repoctl/template-assets.md +116 -0
- package/templates/vitepress/repoctl/templates.md +3 -0
- package/templates/vitepress/repoctl/troubleshooting.md +15 -3
- package/templates/vitepress/repoctl/workflows.md +26 -13
- package/templates/vitepress/tools/index.md +38 -0
- package/templates/vitepress/tools/llms-txt.md +4 -24
|
@@ -5,7 +5,7 @@ This page focuses on high-value repoctl commands and options.
|
|
|
5
5
|
## Main Entry
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
pnpm exec repo
|
|
8
|
+
pnpm exec repo init
|
|
9
9
|
pnpm exec repo doctor
|
|
10
10
|
pnpm exec repo templates
|
|
11
11
|
pnpm exec repo new
|
|
@@ -15,20 +15,20 @@ pnpm exec repo check
|
|
|
15
15
|
Generated repositories also expose:
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
pnpm
|
|
19
|
-
pnpm doctor
|
|
20
|
-
pnpm new
|
|
21
|
-
pnpm check
|
|
18
|
+
pnpm run repo:init
|
|
19
|
+
pnpm run repo:doctor
|
|
20
|
+
pnpm run repo:new
|
|
21
|
+
pnpm run repo:check
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
## `repo
|
|
24
|
+
## `repo init`
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
|
-
repo
|
|
28
|
-
repo
|
|
29
|
-
repo
|
|
30
|
-
repo
|
|
31
|
-
repo
|
|
27
|
+
repo init
|
|
28
|
+
repo init --yes
|
|
29
|
+
repo init --preset minimal
|
|
30
|
+
repo init --preset standard --force
|
|
31
|
+
repo init --overwrite
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
Use it to initialize recommended workspace defaults. It skips existing managed files by default, appends missing workspace patterns, and supports non-interactive CI usage with `--yes`.
|
|
@@ -42,7 +42,7 @@ repo doctor --json --out reports/doctor.json
|
|
|
42
42
|
repo doctor --markdown --redact --out reports/doctor.md
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
Use it to check root workspace files, Node compatibility, CLI dependency presence, root scripts, config
|
|
45
|
+
Use it to check root workspace files, Node compatibility, CLI dependency presence, `repo:*` root scripts, stale config files, and commit hooks.
|
|
46
46
|
|
|
47
47
|
`--strict` treats warnings as failures. `--redact` removes local absolute paths from shareable reports.
|
|
48
48
|
|
|
@@ -6,7 +6,7 @@ repoctl recommends one root config file:
|
|
|
6
6
|
repoctl.config.ts
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
`monorepo.config.ts`
|
|
9
|
+
`monorepo.config.ts` is no longer loaded at runtime. Rename it to `repoctl.config.ts` before running repoctl.
|
|
10
10
|
|
|
11
11
|
## Minimal Config
|
|
12
12
|
|
|
@@ -26,15 +26,15 @@ If the repository was generated from this template, the dependency and root scri
|
|
|
26
26
|
|
|
27
27
|
```bash
|
|
28
28
|
pnpm install
|
|
29
|
-
pnpm exec repo
|
|
29
|
+
pnpm exec repo init
|
|
30
30
|
pnpm exec repo doctor
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
| Command | Purpose
|
|
34
|
-
| -------------- |
|
|
35
|
-
| `pnpm install` | Install workspace dependencies and local links
|
|
36
|
-
| `repo
|
|
37
|
-
| `repo doctor` | Check root files, Node version, CLI dependency, config
|
|
33
|
+
| Command | Purpose |
|
|
34
|
+
| -------------- | ----------------------------------------------------------------------------- |
|
|
35
|
+
| `pnpm install` | Install workspace dependencies and local links |
|
|
36
|
+
| `repo init` | Add recommended scripts, workspace patterns, and tooling entries |
|
|
37
|
+
| `repo doctor` | Check root files, Node version, CLI dependency, stale config files, and hooks |
|
|
38
38
|
|
|
39
39
|
Fix blocking issues reported by `doctor`, then run it again.
|
|
40
40
|
|
|
@@ -61,23 +61,23 @@ pnpm exec repo new sdk --template tsdown --json --out plans/sdk.json
|
|
|
61
61
|
|
|
62
62
|
`--json` and `--out` imply `--dry-run`, which makes them suitable for CI, editor integrations, and scripts.
|
|
63
63
|
|
|
64
|
-
## Use
|
|
64
|
+
## Use Root Scripts
|
|
65
65
|
|
|
66
|
-
After `repo
|
|
66
|
+
After `repo init`, daily commands can be shorter:
|
|
67
67
|
|
|
68
68
|
```bash
|
|
69
|
-
pnpm
|
|
70
|
-
pnpm doctor
|
|
71
|
-
pnpm new sdk --template tsdown
|
|
72
|
-
pnpm check
|
|
69
|
+
pnpm run repo:init
|
|
70
|
+
pnpm run repo:doctor -- --json
|
|
71
|
+
pnpm run repo:new -- sdk --template tsdown
|
|
72
|
+
pnpm run repo:check
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
| Root script
|
|
76
|
-
|
|
|
77
|
-
| `pnpm
|
|
78
|
-
| `pnpm doctor` | `pnpm exec repo doctor` |
|
|
79
|
-
| `pnpm new` | `pnpm exec repo new` |
|
|
80
|
-
| `pnpm check`
|
|
75
|
+
| Root script | Equivalent CLI |
|
|
76
|
+
| ------------------------------ | ---------------------------- |
|
|
77
|
+
| `pnpm run repo:init` | `pnpm exec repo init` |
|
|
78
|
+
| `pnpm run repo:doctor -- args` | `pnpm exec repo doctor args` |
|
|
79
|
+
| `pnpm run repo:new -- args` | `pnpm exec repo new args` |
|
|
80
|
+
| `pnpm run repo:check` | `pnpm exec repo check` |
|
|
81
81
|
|
|
82
82
|
## Verify Before Committing
|
|
83
83
|
|
|
@@ -91,7 +91,7 @@ pnpm test
|
|
|
91
91
|
Or use the repoctl verification entry:
|
|
92
92
|
|
|
93
93
|
```bash
|
|
94
|
-
pnpm check
|
|
94
|
+
pnpm run repo:check
|
|
95
95
|
pnpm exec repo check --dry-run
|
|
96
96
|
pnpm exec repo check --json --out reports/check-plan.json
|
|
97
97
|
```
|
|
@@ -8,7 +8,7 @@ The CLI does not replace pnpm, Turborepo, or changesets. It gives teams a stable
|
|
|
8
8
|
|
|
9
9
|
| Goal | Command |
|
|
10
10
|
| ----------------------------------------------------- | ------------------------ |
|
|
11
|
-
| Add recommended scripts and workspace defaults | `pnpm exec repo
|
|
11
|
+
| Add recommended scripts and workspace defaults | `pnpm exec repo init` |
|
|
12
12
|
| Check whether a repository is ready to develop | `pnpm exec repo doctor` |
|
|
13
13
|
| Create a package, app, docs site, service, or CLI | `pnpm exec repo new` |
|
|
14
14
|
| Reproduce the recommended pre-commit or pre-push flow | `pnpm exec repo check` |
|
|
@@ -17,21 +17,21 @@ The CLI does not replace pnpm, Turborepo, or changesets. It gives teams a stable
|
|
|
17
17
|
|
|
18
18
|
## Recommended Command Layers
|
|
19
19
|
|
|
20
|
-
### Root Scripts
|
|
20
|
+
### repo:\* Root Scripts
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
|
-
pnpm
|
|
24
|
-
pnpm doctor
|
|
25
|
-
pnpm new
|
|
26
|
-
pnpm check
|
|
23
|
+
pnpm run repo:init
|
|
24
|
+
pnpm run repo:doctor
|
|
25
|
+
pnpm run repo:new
|
|
26
|
+
pnpm run repo:check
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
These are the best commands for day-to-day team docs.
|
|
29
|
+
These are the best commands for day-to-day team docs. They are short, explicit, and do not collide with pnpm built-in commands.
|
|
30
30
|
|
|
31
31
|
### Explicit CLI Calls
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
|
-
pnpm exec repo
|
|
34
|
+
pnpm exec repo init
|
|
35
35
|
pnpm exec repo doctor
|
|
36
36
|
pnpm exec repo templates
|
|
37
37
|
pnpm exec repo new sdk --template tsdown
|
|
@@ -51,9 +51,9 @@ pnpm exec repo config inspect
|
|
|
51
51
|
|
|
52
52
|
Grouped commands are for maintainers and automation that need finer control.
|
|
53
53
|
|
|
54
|
-
##
|
|
54
|
+
## Command Entrypoints
|
|
55
55
|
|
|
56
|
-
The package
|
|
56
|
+
The package exposes multiple bins:
|
|
57
57
|
|
|
58
58
|
```bash
|
|
59
59
|
pnpm exec repoctl doctor
|
|
@@ -6,14 +6,14 @@ Start here when you know what you want to do, but not which repoctl command to u
|
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
pnpm install
|
|
9
|
-
pnpm doctor
|
|
9
|
+
pnpm run repo:doctor
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
If
|
|
12
|
+
If the `repo:*` scripts do not exist yet:
|
|
13
13
|
|
|
14
14
|
```bash
|
|
15
15
|
pnpm add -D repoctl
|
|
16
|
-
pnpm exec repo
|
|
16
|
+
pnpm exec repo init --yes
|
|
17
17
|
pnpm exec repo doctor
|
|
18
18
|
```
|
|
19
19
|
|
|
@@ -23,7 +23,7 @@ Keep reading: [Getting Started](./getting-started.md).
|
|
|
23
23
|
|
|
24
24
|
```bash
|
|
25
25
|
pnpm add -D repoctl
|
|
26
|
-
pnpm exec repo
|
|
26
|
+
pnpm exec repo init --yes
|
|
27
27
|
pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
|
|
28
28
|
pnpm exec repo upgrade --no-overwrite
|
|
29
29
|
pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
|
|
@@ -42,7 +42,7 @@ pnpm exec repo new docs --template vitepress --dry-run
|
|
|
42
42
|
For daily development, root scripts also work:
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
|
-
pnpm new sdk --template tsdown
|
|
45
|
+
pnpm run repo:new -- sdk --template tsdown
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
Keep reading: [Templates](./templates.md).
|
|
@@ -50,7 +50,7 @@ Keep reading: [Templates](./templates.md).
|
|
|
50
50
|
## I Want To Check Before Committing
|
|
51
51
|
|
|
52
52
|
```bash
|
|
53
|
-
pnpm check
|
|
53
|
+
pnpm run repo:check
|
|
54
54
|
pnpm exec repo check --dry-run
|
|
55
55
|
pnpm exec repo check --full
|
|
56
56
|
```
|
|
@@ -67,7 +67,7 @@ Keep only:
|
|
|
67
67
|
repoctl.config.ts
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
-
`monorepo.config.ts` is
|
|
70
|
+
`monorepo.config.ts` is no longer loaded at runtime; rename it to `repoctl.config.ts`.
|
|
71
71
|
|
|
72
72
|
### Unknown Template Key
|
|
73
73
|
|
|
@@ -84,7 +84,7 @@ Explicit `--template` values are validated first. Invalid keys fail with suggest
|
|
|
84
84
|
Use non-interactive options:
|
|
85
85
|
|
|
86
86
|
```bash
|
|
87
|
-
repo
|
|
87
|
+
repo init --yes
|
|
88
88
|
repo upgrade --no-overwrite
|
|
89
89
|
repo check --json --out reports/check-plan.json
|
|
90
90
|
```
|
|
@@ -6,25 +6,25 @@ repoctl commands have two audiences: humans using short daily commands, and auto
|
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
pnpm install
|
|
9
|
-
pnpm doctor
|
|
10
|
-
pnpm new sdk --template tsdown
|
|
11
|
-
pnpm check
|
|
9
|
+
pnpm run repo:doctor
|
|
10
|
+
pnpm run repo:new -- sdk --template tsdown
|
|
11
|
+
pnpm run repo:check
|
|
12
12
|
pnpm build
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
| Step
|
|
16
|
-
|
|
|
17
|
-
| `pnpm install`
|
|
18
|
-
| `pnpm doctor`
|
|
19
|
-
| `pnpm new`
|
|
20
|
-
| `pnpm check`
|
|
21
|
-
| `pnpm build`
|
|
15
|
+
| Step | What It Proves |
|
|
16
|
+
| ---------------------- | ------------------------------------------------------- |
|
|
17
|
+
| `pnpm install` | Workspace dependencies and local links are ready |
|
|
18
|
+
| `pnpm run repo:doctor` | Root files, Node, scripts, config, and hooks are usable |
|
|
19
|
+
| `pnpm run repo:new` | New packages follow template conventions |
|
|
20
|
+
| `pnpm run repo:check` | The lightweight local verification flow is reproducible |
|
|
21
|
+
| `pnpm build` | The workspace build graph has no obvious breakage |
|
|
22
22
|
|
|
23
23
|
## Adopt An Existing Repository
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
26
|
pnpm add -D repoctl
|
|
27
|
-
pnpm exec repo
|
|
27
|
+
pnpm exec repo init --yes
|
|
28
28
|
pnpm exec repo doctor --markdown --out reports/doctor.md
|
|
29
29
|
pnpm exec repo upgrade --no-overwrite
|
|
30
30
|
pnpm exec repo doctor
|
|
@@ -75,7 +75,7 @@ repo verify pre-push
|
|
|
75
75
|
|
|
76
76
|
| Scenario | Option |
|
|
77
77
|
| ------------------------------------- | -------------------------------------------------- |
|
|
78
|
-
| Accept setup defaults | `repo
|
|
78
|
+
| Accept setup defaults | `repo init --yes` |
|
|
79
79
|
| Preserve changed files during upgrade | `repo upgrade --no-overwrite` |
|
|
80
80
|
| Explicitly overwrite standard assets | `repo upgrade --yes` or `repo upgrade --overwrite` |
|
|
81
81
|
| Preview only | `--dry-run` |
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
pnpm add -D repoctl
|
|
13
|
-
pnpm exec repo
|
|
13
|
+
pnpm exec repo init
|
|
14
14
|
pnpm exec repo doctor
|
|
15
15
|
pnpm exec repo new
|
|
16
16
|
pnpm exec repo check
|
|
@@ -19,7 +19,7 @@ pnpm exec repo check
|
|
|
19
19
|
模板生成仓库里可以使用更短的根脚本:
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
pnpm
|
|
22
|
+
pnpm run repo:init
|
|
23
23
|
pnpm doctor
|
|
24
24
|
pnpm new
|
|
25
25
|
pnpm check
|
|
@@ -31,7 +31,7 @@ pnpm check
|
|
|
31
31
|
|
|
32
32
|
| 命令 | 解决的问题 |
|
|
33
33
|
| -------------- | ----------------------------------------------------- |
|
|
34
|
-
| `repo
|
|
34
|
+
| `repo init` | 补齐仓库默认脚本、workspace patterns 和基础工具链入口 |
|
|
35
35
|
| `repo doctor` | 判断仓库当前是否可用,并输出可保存的诊断报告 |
|
|
36
36
|
| `repo new` | 从内置模板创建包、应用、服务、文档站或 CLI |
|
|
37
37
|
| `repo check` | 预览或执行提交前推荐校验 |
|
|
@@ -17,7 +17,7 @@ hero:
|
|
|
17
17
|
link: /repoctl/commands
|
|
18
18
|
- theme: alt
|
|
19
19
|
text: AI 文档入口
|
|
20
|
-
link: /
|
|
20
|
+
link: /ai/
|
|
21
21
|
|
|
22
22
|
features:
|
|
23
23
|
- title: 从已有仓库开始
|
|
@@ -34,7 +34,7 @@ features:
|
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
36
|
pnpm add -D repoctl
|
|
37
|
-
pnpm exec repo
|
|
37
|
+
pnpm exec repo init
|
|
38
38
|
pnpm exec repo doctor
|
|
39
39
|
pnpm exec repo new
|
|
40
40
|
pnpm exec repo check
|
|
@@ -43,10 +43,10 @@ pnpm exec repo check
|
|
|
43
43
|
在由模板生成的仓库里,同一套工作流会暴露成更短的根脚本:
|
|
44
44
|
|
|
45
45
|
```bash
|
|
46
|
-
pnpm
|
|
47
|
-
pnpm doctor
|
|
48
|
-
pnpm new
|
|
49
|
-
pnpm check
|
|
46
|
+
pnpm run repo:init
|
|
47
|
+
pnpm run repo:doctor
|
|
48
|
+
pnpm run repo:new
|
|
49
|
+
pnpm run repo:check
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
## 你可以继续阅读
|
|
@@ -55,9 +55,12 @@ pnpm check
|
|
|
55
55
|
- [快速开始](./repoctl/getting-started.md)
|
|
56
56
|
- [接入已有仓库](./repoctl/adopt-existing.md)
|
|
57
57
|
- [按场景选命令](./repoctl/scenarios.md)
|
|
58
|
+
- [执行模型](./repoctl/execution-model.md)
|
|
58
59
|
- [命令速查](./repoctl/commands.md)
|
|
60
|
+
- [校验链路](./repoctl/checks.md)
|
|
61
|
+
- [doctor 诊断](./repoctl/doctor.md)
|
|
59
62
|
- [配置文件](./repoctl/config.md)
|
|
60
63
|
- [模板与创建](./repoctl/templates.md)
|
|
64
|
+
- [模板资产治理](./repoctl/template-assets.md)
|
|
61
65
|
- [工作流与 CI](./repoctl/workflows.md)
|
|
62
|
-
- [
|
|
63
|
-
- [知识库:为什么往 monorepo 方向演进](./monorepo/index.md)
|
|
66
|
+
- [报告与自动化输出](./repoctl/reports.md)
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: repoctl 文档站的知识库入口,汇总 monorepo 管理、现代 npm 包和 JavaScript 模块化基础。
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# 知识库
|
|
6
|
+
|
|
7
|
+
知识库用于解释 repoctl 背后的工程背景。这里不放命令速查,而是回答为什么要这样组织仓库、包、构建和发布流程。
|
|
8
|
+
|
|
9
|
+
## 1. monorepo 主题
|
|
10
|
+
|
|
11
|
+
| 页面 | 适合解决的问题 |
|
|
12
|
+
| -------------------------------------------------- | ---------------------------------- |
|
|
13
|
+
| [为什么往 monorepo 方向演进](../monorepo/index.md) | 判断多包仓库是否值得合并管理 |
|
|
14
|
+
| [如何管理 monorepo](../monorepo/manage.md) | 理解 workspace、任务编排和依赖边界 |
|
|
15
|
+
| [发包与变更日志](../monorepo/publish.md) | 设计 changeset、版本和发布链路 |
|
|
16
|
+
| [monorepo 命令参考](../monorepo/commands.md) | 查看通用 monorepo 操作命令 |
|
|
17
|
+
| [monorepo 模板体系](../monorepo/templates.md) | 理解模板如何减少重复初始化 |
|
|
18
|
+
| [monorepo 排障](../monorepo/troubleshooting.md) | 排查依赖、构建、类型和发布问题 |
|
|
19
|
+
|
|
20
|
+
## 2. 现代 npm 包主题
|
|
21
|
+
|
|
22
|
+
| 页面 | 适合解决的问题 |
|
|
23
|
+
| ------------------------------------------------------ | ---------------------------------- |
|
|
24
|
+
| [如何复用 js 代码](../why/how-to-reuse-js-code.md) | 从复制文件演进到发布包 |
|
|
25
|
+
| [什么是 npm 包](../why/what-is-npm-package.md) | 理解 package.json、入口和安装方式 |
|
|
26
|
+
| [如何发布 npm 包](../why/publish-basic-npm-package.md) | 走通最小 npm 发布流程 |
|
|
27
|
+
| [改进并发布现代 npm 包](../why/index.md) | 把普通包升级成更规范的现代包 |
|
|
28
|
+
| [现代包指南](../why/modern/index.md) | 汇总类型、入口、模块格式和构建工具 |
|
|
29
|
+
|
|
30
|
+
## 3. 阅读顺序
|
|
31
|
+
|
|
32
|
+
如果你第一次接触 monorepo,建议按下面顺序阅读:
|
|
33
|
+
|
|
34
|
+
```txt
|
|
35
|
+
为什么 monorepo
|
|
36
|
+
-> 如何管理 monorepo
|
|
37
|
+
-> 什么是 npm 包
|
|
38
|
+
-> 现代包指南
|
|
39
|
+
-> 发包与变更日志
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
如果你已经在维护仓库,可以直接从具体问题进入:
|
|
43
|
+
|
|
44
|
+
| 你遇到的问题 | 建议入口 |
|
|
45
|
+
| ----------------------------- | ----------------------------------------------- |
|
|
46
|
+
| workspace 包互相引用不清楚 | [如何管理 monorepo](../monorepo/manage.md) |
|
|
47
|
+
| 不确定 CJS、ESM、types 怎么配 | [现代包指南](../why/modern/index.md) |
|
|
48
|
+
| 发布后使用方拿不到类型 | [类型声明](../why/modern/dts.md) |
|
|
49
|
+
| 包入口太多、导入路径混乱 | [包入口](../why/modern/package-entry-points.md) |
|
|
50
|
+
| CI 和发版流程容易漂移 | [发包与变更日志](../monorepo/publish.md) |
|
|
@@ -12,10 +12,10 @@ monorepo 的难点通常不是“能不能跑某个工具”,而是团队成
|
|
|
12
12
|
|
|
13
13
|
repoctl 把命令分成三层:
|
|
14
14
|
|
|
15
|
-
| 层级 | 示例
|
|
16
|
-
| -------- |
|
|
17
|
-
| 根脚本 | `pnpm doctor` / `pnpm new`
|
|
18
|
-
| 主 CLI | `pnpm exec repo doctor`
|
|
19
|
-
| 分组命令 | `repo ws ls` / `repo env support`
|
|
15
|
+
| 层级 | 示例 | 适合场景 |
|
|
16
|
+
| -------- | -------------------------------------------- | -------------------- |
|
|
17
|
+
| 根脚本 | `pnpm run repo:doctor` / `pnpm run repo:new` | 日常开发和团队教程 |
|
|
18
|
+
| 主 CLI | `pnpm exec repo doctor` | CI、脚本、排障和文档 |
|
|
19
|
+
| 分组命令 | `repo ws ls` / `repo env support` | 维护者和自动化 |
|
|
20
20
|
|
|
21
21
|
保留这个旧页面,是为了让已有链接继续可用,同时把读者导向新的 repoctl 命令文档。
|
|
@@ -40,15 +40,15 @@
|
|
|
40
40
|
|
|
41
41
|
这不是一个“什么都能配”的框架,而是一套偏实战、偏收敛的默认值:
|
|
42
42
|
|
|
43
|
-
| 维度 | 默认选择
|
|
44
|
-
| -------- |
|
|
45
|
-
| 包管理 | `pnpm workspace`
|
|
46
|
-
| 任务编排 | `turborepo`
|
|
47
|
-
| 语言 | TypeScript 优先
|
|
48
|
-
| 校验链路 | ESLint + Stylelint + typecheck + Vitest
|
|
49
|
-
| 提交规范 | Husky + lint-staged + commitlint
|
|
50
|
-
| 发包 | changesets
|
|
51
|
-
| 命令入口 | `repo` 为主,`repoctl`
|
|
43
|
+
| 维度 | 默认选择 |
|
|
44
|
+
| -------- | --------------------------------------- |
|
|
45
|
+
| 包管理 | `pnpm workspace` |
|
|
46
|
+
| 任务编排 | `turborepo` |
|
|
47
|
+
| 语言 | TypeScript 优先 |
|
|
48
|
+
| 校验链路 | ESLint + Stylelint + typecheck + Vitest |
|
|
49
|
+
| 提交规范 | Husky + lint-staged + commitlint |
|
|
50
|
+
| 发包 | changesets |
|
|
51
|
+
| 命令入口 | `repo` 为主,`repoctl` 为完整包名入口 |
|
|
52
52
|
|
|
53
53
|
这些选择的目的只有一个:减少“每个项目重新想一遍”的成本。
|
|
54
54
|
|
|
@@ -74,10 +74,10 @@
|
|
|
74
74
|
### 1. 更短的日常命令
|
|
75
75
|
|
|
76
76
|
```bash
|
|
77
|
-
pnpm
|
|
78
|
-
pnpm doctor
|
|
79
|
-
pnpm new
|
|
80
|
-
pnpm check
|
|
77
|
+
pnpm exec repo init
|
|
78
|
+
pnpm exec repo doctor
|
|
79
|
+
pnpm run repo:new
|
|
80
|
+
pnpm run repo:check
|
|
81
81
|
```
|
|
82
82
|
|
|
83
83
|
不用先背完整 CLI,先把日常路径跑顺。
|
|
@@ -91,7 +91,7 @@ pnpm check
|
|
|
91
91
|
- Node 版本对不对
|
|
92
92
|
- 有没有安装 CLI 依赖
|
|
93
93
|
- 根脚本齐不齐
|
|
94
|
-
-
|
|
94
|
+
- 是否仍残留已废弃的 `monorepo.config.ts`
|
|
95
95
|
- Husky / lint-staged 链路是不是半残状态
|
|
96
96
|
|
|
97
97
|
### 3. `repo upgrade` 这种面向存量仓库的同步命令
|
|
@@ -8,9 +8,9 @@
|
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
pnpm install
|
|
11
|
-
pnpm doctor
|
|
12
|
-
pnpm new
|
|
13
|
-
pnpm check
|
|
11
|
+
pnpm exec repo doctor
|
|
12
|
+
pnpm run repo:new
|
|
13
|
+
pnpm run repo:check
|
|
14
14
|
pnpm build
|
|
15
15
|
```
|
|
16
16
|
|
|
@@ -19,7 +19,7 @@ pnpm build
|
|
|
19
19
|
如果你在接入一个旧仓库,再多加一步:
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
pnpm
|
|
22
|
+
pnpm exec repo init
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
这个工作流背后的顺序是:
|
|
@@ -41,10 +41,10 @@ pnpm setup
|
|
|
41
41
|
这是最推荐的入口:
|
|
42
42
|
|
|
43
43
|
```bash
|
|
44
|
-
pnpm
|
|
45
|
-
pnpm new
|
|
46
|
-
pnpm doctor
|
|
47
|
-
pnpm check
|
|
44
|
+
pnpm exec repo init
|
|
45
|
+
pnpm run repo:new
|
|
46
|
+
pnpm exec repo doctor
|
|
47
|
+
pnpm run repo:check
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
适合:
|
|
@@ -59,7 +59,7 @@ pnpm check
|
|
|
59
59
|
当你要明确告诉别人“这是 CLI 行为,不只是 package.json 脚本”时,用:
|
|
60
60
|
|
|
61
61
|
```bash
|
|
62
|
-
pnpm exec repo
|
|
62
|
+
pnpm exec repo init
|
|
63
63
|
pnpm exec repo new
|
|
64
64
|
pnpm exec repo doctor
|
|
65
65
|
pnpm exec repo check
|
|
@@ -81,14 +81,14 @@ repo ai prompt create --name checkout
|
|
|
81
81
|
|
|
82
82
|
## 日常任务对照表
|
|
83
83
|
|
|
84
|
-
| 你想做什么 | 推荐命令
|
|
85
|
-
| ---------------------- |
|
|
86
|
-
| 初始化一个刚接入的仓库 | `pnpm
|
|
87
|
-
| 看仓库当前状态是否健康 | `pnpm doctor`
|
|
88
|
-
| 创建一个新的包或应用 | `pnpm new`
|
|
89
|
-
| 提交前做本地校验 | `pnpm check`
|
|
90
|
-
| 同步模板最新标准资产 | `pnpm exec repo upgrade`
|
|
91
|
-
| 清理演示仓库或非必要包 | `pnpm exec repo clean --yes` | 零安装也可以用 `pnpm dlx repo@latest clean --yes` |
|
|
84
|
+
| 你想做什么 | 推荐命令 | 说明 |
|
|
85
|
+
| ---------------------- | ------------------------------- | ---------------------------------------------------- |
|
|
86
|
+
| 初始化一个刚接入的仓库 | `pnpm exec repo init` | 同步推荐的仓库元信息和基础工程化配置 |
|
|
87
|
+
| 看仓库当前状态是否健康 | `pnpm exec repo doctor` | 先排根目录、Node、脚本、遗留配置、提交链路 |
|
|
88
|
+
| 创建一个新的包或应用 | `pnpm run repo:new` | 支持交互式选择,也支持 `-- --template` |
|
|
89
|
+
| 提交前做本地校验 | `pnpm run repo:check` | 默认对齐推荐 pre-commit / pre-push 逻辑 |
|
|
90
|
+
| 同步模板最新标准资产 | `pnpm exec repo upgrade` | 适合模板升级、老仓库补齐 |
|
|
91
|
+
| 清理演示仓库或非必要包 | `pnpm exec repo ws clean --yes` | 零安装也可以用 `pnpm dlx repo@latest ws clean --yes` |
|
|
92
92
|
|
|
93
93
|
## `doctor`、`check`、`upgrade` 的边界
|
|
94
94
|
|
|
@@ -151,7 +151,7 @@ export default defineMonorepoConfig({
|
|
|
151
151
|
说明:
|
|
152
152
|
|
|
153
153
|
- 优先使用 `repoctl.config.ts`
|
|
154
|
-
- `monorepo.config.ts`
|
|
154
|
+
- `monorepo.config.ts` 已不再加载
|
|
155
155
|
- 两者不能同时存在
|
|
156
156
|
|
|
157
157
|
如果同时存在,现在 CLI 会直接报错,`repo doctor` 也会把它判成阻塞项。
|
|
@@ -161,7 +161,7 @@ export default defineMonorepoConfig({
|
|
|
161
161
|
### 交互式
|
|
162
162
|
|
|
163
163
|
```bash
|
|
164
|
-
pnpm new
|
|
164
|
+
pnpm run repo:new
|
|
165
165
|
```
|
|
166
166
|
|
|
167
167
|
适合第一次使用模板、想先看看有哪些模板可选。
|
|
@@ -208,8 +208,8 @@ pnpm exec repo new utils
|
|
|
208
208
|
|
|
209
209
|
这也是为什么:
|
|
210
210
|
|
|
211
|
-
- `pnpm doctor` 会检查 Husky 与 lint-staged 是否同时存在
|
|
212
|
-
- `pnpm check` 会成为最自然的人工入口
|
|
211
|
+
- `pnpm exec repo doctor` 会检查 Husky 与 lint-staged 是否同时存在
|
|
212
|
+
- `pnpm run repo:check` 会成为最自然的人工入口
|
|
213
213
|
|
|
214
214
|
## 依赖与构建建议
|
|
215
215
|
|
|
@@ -15,6 +15,6 @@ repoctl 排障文档已经集中到:
|
|
|
15
15
|
| 模板创建问题 | 模板 key、目标目录、创建计划 | `repo templates` / `repo new --dry-run` |
|
|
16
16
|
| 提交前校验问题 | staged 文件、workspace 归属、任务路由 | `repo check --dry-run` |
|
|
17
17
|
| 环境差异问题 | Node、pnpm、Git、CI、路径 | `repo env support --markdown --redact` |
|
|
18
|
-
|
|
|
18
|
+
| 遗留配置问题 | `repoctl.config.ts` 与旧配置文件 | `repo config inspect` |
|
|
19
19
|
|
|
20
20
|
旧页面继续保留为知识点索引,具体排查步骤以后优先维护在 repoctl 分区。
|
|
@@ -27,13 +27,13 @@
|
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@braintree/sanitize-url": "^7.1.2",
|
|
30
|
-
"@tailwindcss/vite": "^4.
|
|
30
|
+
"@tailwindcss/vite": "^4.3.0",
|
|
31
31
|
"cytoscape": "^3.33.3",
|
|
32
32
|
"cytoscape-cose-bilkent": "^4.1.0",
|
|
33
33
|
"dayjs": "^1.11.20",
|
|
34
34
|
"debug": "^4.4.3",
|
|
35
35
|
"mermaid": "^11.14.0",
|
|
36
|
-
"tailwindcss": "^4.
|
|
36
|
+
"tailwindcss": "^4.3.0",
|
|
37
37
|
"vitepress": "^1.6.4",
|
|
38
38
|
"vitepress-plugin-llms": "^1.12.2",
|
|
39
39
|
"vitepress-plugin-mermaid": "^2.0.17"
|