@icebreakers/monorepo-templates 0.1.16 → 1.0.0
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/README.md +12 -0
- package/assets/.changeset/config.json +7 -2
- package/assets/.github/workflows/ci.yml +8 -2
- package/assets/.github/workflows/release.yml +2 -2
- package/assets/.husky/commit-msg +1 -1
- package/assets/.husky/pre-commit +1 -1
- package/assets/.husky/pre-push +5 -0
- package/assets/AGENTS.md +8 -7
- package/assets/commitlint.config.ts +2 -2
- package/assets/eslint.config.js +2 -6
- package/assets/lint-staged.config.js +3 -0
- package/assets/package.json +39 -28
- package/assets/repoctl.config.ts +68 -0
- package/assets/stylelint.config.js +2 -2
- package/assets/tooling/ensure-tooling-built.mjs +24 -0
- package/assets/tooling/load-tooling-module.mjs +71 -0
- package/assets/tsconfig.json +1 -49
- package/assets/turbo.json +17 -6
- package/assets/vitest.config.ts +2 -125
- package/assets-data.mjs +4 -2
- package/dist/index.d.mts +22 -1
- package/dist/index.mjs +114 -30
- package/package.json +12 -8
- package/template-data.mjs +48 -8
- package/templates/client/eslint.config.js +6 -4
- package/templates/client/package.json +22 -22
- package/templates/client/vite.config.ts +4 -3
- package/templates/client/wrangler.jsonc +1 -6
- package/templates/server/package.json +4 -4
- package/templates/server/src/app.ts +4 -4
- package/templates/server/tsconfig.json +1 -2
- package/templates/server/vitest.config.ts +6 -5
- package/templates/server/wrangler.jsonc +1 -6
- package/templates/tsdown/package.json +2 -1
- package/templates/tsdown/test-d/index.test-d.ts +5 -0
- package/templates/tsdown/tsconfig.json +1 -2
- package/templates/tsdown/vitest.config.ts +6 -5
- package/templates/vitepress/.vitepress/config.ts +34 -36
- package/templates/vitepress/getting-started.md +243 -0
- package/templates/vitepress/gitignore +2 -1
- package/templates/vitepress/index.md +144 -79
- package/templates/vitepress/monorepo/commands.md +281 -0
- package/templates/vitepress/monorepo/index.md +103 -34
- package/templates/vitepress/monorepo/manage.md +181 -80
- package/templates/vitepress/monorepo/publish.md +128 -57
- package/templates/vitepress/monorepo/templates.md +67 -0
- package/templates/vitepress/monorepo/troubleshooting.md +207 -0
- package/templates/vitepress/package.json +5 -5
- package/templates/vitepress/thinking.md +1 -1
- package/templates/vitepress/tools/husky.md +7 -2
- package/templates/vitepress/tools/lint-staged.md +15 -1
- package/templates/vitepress/why/examples/usage-cjs/index.js +2 -6
- package/templates/vitepress/why/examples/usage-cjs/package-lock.json +7 -13
- package/templates/vitepress/why/examples/usage-cjs/package.json +2 -2
- package/templates/vitepress/why/examples/usage-esm/index.js +2 -2
- package/templates/vitepress/why/examples/usage-esm/package-lock.json +7 -13
- package/templates/vitepress/why/examples/usage-esm/package.json +2 -2
- package/templates/vitepress/why/modern/bundlers.md +8 -46
- package/templates/vue-lib/eslint.config.js +6 -4
- package/templates/vue-lib/package.json +17 -12
- package/templates/vue-lib/test-d/index.test-d.ts +6 -0
- package/templates/vue-lib/tsconfig.test.json +1 -1
- package/templates/vue-lib/vitest.config.ts +8 -5
- package/assets/monorepo.config.ts +0 -22
- package/assets/nano-staged.js +0 -18
- package/templates/tsup/build.config.ts +0 -24
- package/templates/tsup/package.json +0 -49
- package/templates/tsup/src/index.ts +0 -12
- package/templates/tsup/test/index.test.ts +0 -18
- package/templates/tsup/tsconfig.json +0 -15
- package/templates/tsup/tsup.config.ts +0 -18
- package/templates/tsup/vitest.config.ts +0 -15
- package/templates/unbuild/build.config.ts +0 -24
- package/templates/unbuild/package.json +0 -49
- package/templates/unbuild/src/index.ts +0 -9
- package/templates/unbuild/src/utils.ts +0 -5
- package/templates/unbuild/test/index.test.ts +0 -18
- package/templates/unbuild/tsconfig.json +0 -15
- package/templates/unbuild/vitest.config.ts +0 -15
|
@@ -1,42 +1,71 @@
|
|
|
1
1
|
# monorepo 发包与变更日志
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
这套模板默认推荐用 `changesets` 管理版本和 changelog。原因不是“它很流行”,而是它对 monorepo 的工作方式最顺手:
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- 变更是按包记录的
|
|
6
|
+
- 版本升级能自动联动内部依赖
|
|
7
|
+
- changelog 可以稳定产出
|
|
8
|
+
- 很容易接到 CI 里
|
|
6
9
|
|
|
7
|
-
|
|
8
|
-
| ------------ | ------------------------------------------------------------- |
|
|
9
|
-
| 精确记录改动 | 每次变更生成独立的 changeset 文件,说明影响的包与语义版本类型 |
|
|
10
|
-
| 自动生成日志 | 基于 changeset 内容生成结构化的 `CHANGELOG.md` |
|
|
11
|
-
| 语义化版本 | 支持 `major` / `minor` / `patch`,并处理依赖联动升级 |
|
|
12
|
-
| 自动化发布 | 可在 CI 中自动创建版本 PR 或直接发布到 npm |
|
|
10
|
+
## 一条务实的发布流程
|
|
13
11
|
|
|
14
|
-
|
|
12
|
+
先把顺序记住:
|
|
15
13
|
|
|
16
|
-
|
|
14
|
+
1. 写代码
|
|
15
|
+
2. 跑校验
|
|
16
|
+
3. 生成 changeset
|
|
17
|
+
4. 合并后 version / publish
|
|
17
18
|
|
|
18
|
-
|
|
19
|
+
对应到命令,一般是:
|
|
19
20
|
|
|
20
21
|
```bash
|
|
21
|
-
pnpm
|
|
22
|
-
pnpm
|
|
22
|
+
pnpm build
|
|
23
|
+
pnpm lint
|
|
24
|
+
pnpm typecheck
|
|
25
|
+
pnpm tsd
|
|
26
|
+
pnpm test
|
|
27
|
+
pnpm changeset
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
如果你改的是公开类型或类库 API,`tsd` 不要省。
|
|
31
|
+
|
|
32
|
+
## 为什么推荐 `changesets`
|
|
33
|
+
|
|
34
|
+
| 需求 | `changesets` 的做法 |
|
|
35
|
+
| -------------- | ----------------------------------------- |
|
|
36
|
+
| 记录哪些包变了 | 每次变更生成单独的 `.changeset/*.md` 文件 |
|
|
37
|
+
| 控制版本类型 | 明确选择 `patch` / `minor` / `major` |
|
|
38
|
+
| 自动生成日志 | `changeset version` 统一产出 changelog |
|
|
39
|
+
| 联动内部包版本 | 自动改内部依赖引用 |
|
|
40
|
+
| CI 自动发布 | 可接 `changesets/action` |
|
|
41
|
+
|
|
42
|
+
## 日常开发阶段怎么做
|
|
43
|
+
|
|
44
|
+
### 1. 本地先把质量门过掉
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pnpm build
|
|
48
|
+
pnpm lint
|
|
49
|
+
pnpm typecheck
|
|
50
|
+
pnpm tsd
|
|
51
|
+
pnpm test
|
|
23
52
|
```
|
|
24
53
|
|
|
25
|
-
|
|
54
|
+
这一点和仓库的提交要求是一致的。
|
|
26
55
|
|
|
27
|
-
### 2.
|
|
56
|
+
### 2. 记录 changeset
|
|
28
57
|
|
|
29
58
|
```bash
|
|
30
59
|
pnpm changeset
|
|
31
60
|
```
|
|
32
61
|
|
|
33
|
-
|
|
62
|
+
按提示选择:
|
|
34
63
|
|
|
35
|
-
1.
|
|
36
|
-
2.
|
|
37
|
-
3.
|
|
64
|
+
1. 哪些包受影响
|
|
65
|
+
2. 这些包分别是 `patch` / `minor` / `major`
|
|
66
|
+
3. 这次改动怎么写进 changelog
|
|
38
67
|
|
|
39
|
-
|
|
68
|
+
示例:
|
|
40
69
|
|
|
41
70
|
```md
|
|
42
71
|
---
|
|
@@ -44,33 +73,38 @@ pnpm changeset
|
|
|
44
73
|
"@my/ui": patch
|
|
45
74
|
---
|
|
46
75
|
|
|
47
|
-
- feat(utils):
|
|
48
|
-
- fix(ui):
|
|
76
|
+
- feat(utils): 新增时间格式化工具
|
|
77
|
+
- fix(ui): 修复按钮禁用态样式
|
|
49
78
|
```
|
|
50
79
|
|
|
51
|
-
### 3.
|
|
80
|
+
### 3. 合并前看一眼影响面
|
|
52
81
|
|
|
53
|
-
|
|
54
|
-
pnpm changeset version
|
|
55
|
-
```
|
|
82
|
+
changeset 文件本身就是最便宜的“发布预告”。代码评审时顺手看一下,通常就能避免:
|
|
56
83
|
|
|
57
|
-
|
|
84
|
+
- 漏记某个包
|
|
85
|
+
- 版本类型选错
|
|
86
|
+
- changelog 写得太含糊
|
|
58
87
|
|
|
59
|
-
|
|
60
|
-
- 调整内部依赖引用。
|
|
61
|
-
- 为每个包写入或追加 `CHANGELOG.md`。
|
|
88
|
+
## 发布阶段怎么做
|
|
62
89
|
|
|
63
|
-
###
|
|
90
|
+
### 手动流程
|
|
64
91
|
|
|
65
92
|
```bash
|
|
66
|
-
pnpm changeset
|
|
93
|
+
pnpm changeset version
|
|
94
|
+
pnpm publish-packages
|
|
67
95
|
```
|
|
68
96
|
|
|
69
|
-
|
|
97
|
+
`changeset version` 会做这些事:
|
|
98
|
+
|
|
99
|
+
- 更新受影响包的版本号
|
|
100
|
+
- 调整内部依赖版本
|
|
101
|
+
- 生成或更新每个包的 `CHANGELOG.md`
|
|
102
|
+
|
|
103
|
+
### CI 自动流程
|
|
70
104
|
|
|
71
|
-
|
|
105
|
+
模板推荐结合 `changesets/action`。
|
|
72
106
|
|
|
73
|
-
|
|
107
|
+
一个常见的工作流结构如下:
|
|
74
108
|
|
|
75
109
|
```yaml
|
|
76
110
|
name: Release
|
|
@@ -98,8 +132,6 @@ jobs:
|
|
|
98
132
|
- uses: pnpm/action-setup@v4
|
|
99
133
|
- uses: actions/setup-node@v4
|
|
100
134
|
with:
|
|
101
|
-
# 这是为了使用新版本的 npm, 只有 npm@11.5.x 以上版本才支持 OIDC
|
|
102
|
-
# 否则你就必须使用 npm i -g npm@latest 来升级 npm 版本
|
|
103
135
|
node-version: 24
|
|
104
136
|
cache: pnpm
|
|
105
137
|
registry-url: https://registry.npmjs.org
|
|
@@ -110,33 +142,72 @@ jobs:
|
|
|
110
142
|
publish: pnpm publish-packages
|
|
111
143
|
env:
|
|
112
144
|
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
113
|
-
# npm/action-oidc-auth 会设置 NODE_AUTH_TOKEN 供 publish 使用
|
|
114
145
|
```
|
|
115
146
|
|
|
116
|
-
|
|
147
|
+
## 关于 npm 鉴权
|
|
148
|
+
|
|
149
|
+
现在更推荐在 CI 里使用 OIDC,而不是长期保存一个会过期的 `NPM_TOKEN`。
|
|
150
|
+
|
|
151
|
+
原因很现实:
|
|
152
|
+
|
|
153
|
+
- token 会过期
|
|
154
|
+
- token 泄漏风险更高
|
|
155
|
+
- OIDC 更适合自动化发布
|
|
156
|
+
|
|
157
|
+
所以工作流里建议保留:
|
|
158
|
+
|
|
159
|
+
```yaml
|
|
160
|
+
permissions:
|
|
161
|
+
id-token: write
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## 常见发布约束
|
|
165
|
+
|
|
166
|
+
### 私有包不会被发布
|
|
167
|
+
|
|
168
|
+
如果一个包是:
|
|
169
|
+
|
|
170
|
+
```json
|
|
171
|
+
{
|
|
172
|
+
"private": true
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
那么它通常不会进入 npm 发布流程。
|
|
177
|
+
|
|
178
|
+
### 没有 changeset 就不会有版本 PR
|
|
179
|
+
|
|
180
|
+
如果你改了公开包,却没有提交 `.changeset/*.md`,那么后续版本流转通常会断掉。
|
|
181
|
+
|
|
182
|
+
### 先 build 再发
|
|
183
|
+
|
|
184
|
+
这个仓库的约定很明确:先 build,再 lint / typecheck / tsd / test,再谈发布。不要跳步。
|
|
185
|
+
|
|
186
|
+
## 常见问题
|
|
187
|
+
|
|
188
|
+
### 为什么没有生成 changelog?
|
|
189
|
+
|
|
190
|
+
通常是下面几种原因:
|
|
191
|
+
|
|
192
|
+
- 没有执行 `pnpm changeset version`
|
|
193
|
+
- `.changeset/*.md` 没有提交
|
|
194
|
+
- 受影响包实际没有进入版本计算
|
|
117
195
|
|
|
118
|
-
|
|
196
|
+
### 如何跳过某个包的发布?
|
|
119
197
|
|
|
120
|
-
|
|
198
|
+
- 在 changeset 里不要勾选它
|
|
199
|
+
- 或者把它标记为 `private: true`
|
|
121
200
|
|
|
122
|
-
|
|
123
|
-
| -------------- | ---------- | -------------- | -------- |
|
|
124
|
-
| 支持多包 | ✅ | ✅ | ❌ |
|
|
125
|
-
| 自动 changelog | ✅ | 部分支持 | ❌ |
|
|
126
|
-
| 逐条记录变更 | ✅ | ❌ | ❌ |
|
|
127
|
-
| 维护活跃度 | 高 | 低 | 需自养 |
|
|
128
|
-
| CI/CD 集成 | 简单 | 相对繁琐 | 完全手工 |
|
|
201
|
+
### 为什么要在 PR 阶段就看 changeset?
|
|
129
202
|
|
|
130
|
-
|
|
203
|
+
因为它本质上是在回答一个非常具体的问题:
|
|
131
204
|
|
|
132
|
-
|
|
133
|
-
- **为何 `CHANGELOG` 没生成?** 确认是否执行了 `pnpm changeset version` 并提交了 `.changeset` 文件。
|
|
134
|
-
- **如何避免发布某些包?** 在创建 changeset 时不勾选即可,或将包标记为 `private: true`。
|
|
205
|
+
“这次改动准备怎么影响发布面?”
|
|
135
206
|
|
|
136
|
-
|
|
207
|
+
这个问题越早看,越不容易在合并后补救。
|
|
137
208
|
|
|
138
|
-
|
|
139
|
-
- [模板中的发布工作流示例](https://github.com/sonofmagic/monorepo-template/blob/main/.github/workflows/release.yml)
|
|
140
|
-
- [管理指南:pnpm + Turborepo + monorepo.config](./manage.md)
|
|
209
|
+
## 继续阅读
|
|
141
210
|
|
|
142
|
-
|
|
211
|
+
- [如何管理 monorepo](./manage.md)
|
|
212
|
+
- [命令速查](./commands.md)
|
|
213
|
+
- [排障指南](./troubleshooting.md)
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# 模板速查
|
|
2
|
+
|
|
3
|
+
内置模板由 `@icebreakers/monorepo-templates` 维护,CLI、脚手架和文档都复用同一份模板元数据。
|
|
4
|
+
|
|
5
|
+
## 模板列表
|
|
6
|
+
|
|
7
|
+
| Key | Category | Source | Default target | Description |
|
|
8
|
+
| ------------- | -------- | --------------------- | ------------------ | ----------------------------------- |
|
|
9
|
+
| `tsdown` | library | `templates/tsdown` | `packages/tsdown` | 使用 tsdown 构建的 TypeScript 库包 |
|
|
10
|
+
| `vue-lib` | library | `templates/vue-lib` | `packages/vue-lib` | Vue 3 组件库模板,适合沉淀可复用 UI |
|
|
11
|
+
| `vue-hono` | app | `templates/client` | `apps/client` | Vue 3 + Hono 的前后端一体应用模板 |
|
|
12
|
+
| `hono-server` | service | `templates/server` | `apps/server` | Hono API 服务模板 |
|
|
13
|
+
| `vitepress` | docs | `templates/vitepress` | `apps/website` | VitePress 文档站模板 |
|
|
14
|
+
| `cli` | tool | `templates/cli` | `apps/cli` | TypeScript 命令行工具模板 |
|
|
15
|
+
|
|
16
|
+
## 查看模板
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
repo templates
|
|
20
|
+
repo templates tsdown
|
|
21
|
+
repo templates --category library
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
需要给脚本读取时:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
repo templates --json
|
|
28
|
+
repo templates tsdown --json
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
需要同步文档片段时:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
repo templates --markdown
|
|
35
|
+
repo templates tsdown --markdown
|
|
36
|
+
repo templates --markdown --out docs/templates.md
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 创建前预览
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
repo new sdk --template tsdown --dry-run
|
|
43
|
+
repo new website --template vitepress --dry-run
|
|
44
|
+
repo new website --template vitepress --json
|
|
45
|
+
repo new website --template vitepress --json --out plans/website.json
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`--dry-run` 不写入磁盘,只展示模板、源目录、目标目录、package name 和输出的 package json 文件。
|
|
49
|
+
`--json` 输出同一份创建计划的结构化数据,隐含 `--dry-run`,适合 CI、编辑器和自动化脚本。
|
|
50
|
+
`--out <file>` 可以把文本或 JSON 预览写入文件,也隐含 `--dry-run`。
|
|
51
|
+
|
|
52
|
+
显式传入的 `--template` 会先校验。模板 key 拼错时,命令会失败并提示相近 key,而不是静默回退到默认模板。
|
|
53
|
+
|
|
54
|
+
## 健康检查
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
repo templates --check
|
|
58
|
+
repo templates --check --json
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
模板健康检查会确认:
|
|
62
|
+
|
|
63
|
+
- 模板 source / target 没有重复。
|
|
64
|
+
- 每个模板 source 目录都存在。
|
|
65
|
+
- 每个模板根目录都有 `package.json`。
|
|
66
|
+
- 每个模板都有 category 和 description。
|
|
67
|
+
- 模板源目录里没有会被脚手架过滤掉的临时或生成文件。
|
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# 排障指南
|
|
2
|
+
|
|
3
|
+
这一页不讲原理,直接讲最常见的问题和对应动作。
|
|
4
|
+
|
|
5
|
+
## 第一反应:先跑 `repo doctor`
|
|
6
|
+
|
|
7
|
+
如果你不确定问题在哪,先执行:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm doctor
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
需要把诊断结果交给 CI、编辑器或机器人时:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pnpm exec repo doctor --json --out reports/doctor.json
|
|
17
|
+
pnpm exec repo doctor --markdown --redact --out reports/doctor.md
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
需要让 CI 对 warning 也失败时:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm exec repo doctor --strict --json --out reports/doctor.json
|
|
24
|
+
pnpm exec repo doctor --strict --markdown --redact --out reports/doctor.md
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
需要把运行环境一起发给同事、CI 或机器人时:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pnpm exec repo env paths --json --out reports/paths.json
|
|
31
|
+
pnpm exec repo env paths --markdown --redact --out reports/paths.md
|
|
32
|
+
pnpm exec repo config inspect --json --out reports/config.json
|
|
33
|
+
pnpm exec repo config inspect --markdown --redact --out reports/config.md
|
|
34
|
+
pnpm exec repo env info --json --out reports/env.json
|
|
35
|
+
pnpm exec repo env info --markdown --redact --out reports/env.md
|
|
36
|
+
pnpm exec repo env snapshot --json --out reports/snapshot.json
|
|
37
|
+
pnpm exec repo env snapshot --markdown --redact --out reports/snapshot.md
|
|
38
|
+
pnpm exec repo env snapshot --markdown --redact --strict --out reports/snapshot.md
|
|
39
|
+
pnpm exec repo env support --json --out reports/support.json
|
|
40
|
+
pnpm exec repo env support --markdown --redact --out reports/support.md
|
|
41
|
+
pnpm exec repo env support --markdown --redact --strict --out reports/support.md
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`env paths` 会列出 repoctl / monorepo 配置文件的全部候选扩展名,不只检查 `.ts` 文件。
|
|
45
|
+
如果要把环境报告发给外部协作者,优先加 `--redact` 脱敏本机绝对路径;如果是贴到 issue 或 PR 评论里,用 `--markdown` 生成摘要。
|
|
46
|
+
在 CI 中可以再加 `--strict`,这样会先写出排障包,再在 `doctor` 有 fail 或 warn 时返回失败码。
|
|
47
|
+
|
|
48
|
+
它会优先帮你排这些低成本但高频的问题:
|
|
49
|
+
|
|
50
|
+
- 当前目录不是仓库根目录
|
|
51
|
+
- 缺少 `pnpm-workspace.yaml`
|
|
52
|
+
- Node 版本不满足要求
|
|
53
|
+
- 根 `package.json` 没装 `repoctl` / `@icebreakers/monorepo`
|
|
54
|
+
- 根快捷脚本没同步齐
|
|
55
|
+
- `repoctl.config.ts` 与 `monorepo.config.ts` 同时存在
|
|
56
|
+
- `.husky/pre-commit` 和 `lint-staged.config.js` 只配了一半
|
|
57
|
+
|
|
58
|
+
## 常见问题
|
|
59
|
+
|
|
60
|
+
### 1. 提示当前目录不像 monorepo 根目录
|
|
61
|
+
|
|
62
|
+
通常是因为你在子包目录里执行了命令,或者根目录缺少这些文件:
|
|
63
|
+
|
|
64
|
+
```txt
|
|
65
|
+
package.json
|
|
66
|
+
pnpm-workspace.yaml
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
先回到根目录再执行。
|
|
70
|
+
|
|
71
|
+
如果要确认 CLI 实际识别到了哪些 workspace 包,可以输出一份列表:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pnpm exec repo ws ls --json --out reports/workspaces.json
|
|
75
|
+
pnpm exec repo ws ls --markdown --redact --out reports/workspaces.md
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### 2. Node 版本不满足要求
|
|
79
|
+
|
|
80
|
+
看根 `package.json`:
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"engines": {
|
|
85
|
+
"node": ">=20.0.0"
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
切到满足要求的 Node 版本后,再跑:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pnpm install
|
|
94
|
+
pnpm doctor
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### 3. `repoctl.config.ts` 和 `monorepo.config.ts` 同时存在
|
|
98
|
+
|
|
99
|
+
这是明确的冲突状态,不是“都能读”。
|
|
100
|
+
|
|
101
|
+
处理方式:
|
|
102
|
+
|
|
103
|
+
- 保留 `repoctl.config.ts`
|
|
104
|
+
- 删除 `monorepo.config.ts`
|
|
105
|
+
|
|
106
|
+
除非你在迁移历史仓库,否则没有必要双持。
|
|
107
|
+
|
|
108
|
+
### 4. 根脚本没有 `setup` / `new` / `check` / `doctor`
|
|
109
|
+
|
|
110
|
+
先同步一次标准资产:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
pnpm exec repo upgrade
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 5. `repo new --template` 提示未知模板
|
|
117
|
+
|
|
118
|
+
先运行:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
pnpm exec repo templates
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
确认模板 key。`--template` 是严格校验的,拼写错误会直接失败;如果能判断出相近 key,CLI 会额外提示 `did you mean ...`。
|
|
125
|
+
|
|
126
|
+
如果你只是不想等,也可以手动把这些脚本加回根 `package.json`。
|
|
127
|
+
|
|
128
|
+
### 5. 提交前校验没有正常工作
|
|
129
|
+
|
|
130
|
+
先检查这两个文件是不是同时存在:
|
|
131
|
+
|
|
132
|
+
```txt
|
|
133
|
+
.husky/pre-commit
|
|
134
|
+
lint-staged.config.js
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
只存在一个,通常就是半残状态。
|
|
138
|
+
|
|
139
|
+
可选动作:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
pnpm exec repo upgrade
|
|
143
|
+
pnpm check
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### 6. `repo` 命令不可用
|
|
147
|
+
|
|
148
|
+
通常是依赖还没安装,或者当前仓库没把 CLI 包放进根依赖。
|
|
149
|
+
|
|
150
|
+
先执行:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
pnpm install
|
|
154
|
+
pnpm doctor
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
如果根本没有安装 CLI 依赖,补一个即可:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
pnpm add -D repoctl
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## `doctor` 和 `check` 的区别
|
|
164
|
+
|
|
165
|
+
很多人遇到问题会这两个命令来回试,其实职责不同:
|
|
166
|
+
|
|
167
|
+
| 命令 | 更像什么 |
|
|
168
|
+
| -------- | ---------- |
|
|
169
|
+
| `doctor` | 仓库体检 |
|
|
170
|
+
| `check` | 提交前校验 |
|
|
171
|
+
|
|
172
|
+
如果你怀疑是“仓库架子不完整”,先用 `doctor`。
|
|
173
|
+
如果你怀疑是“这次改动过不了 lint / typecheck / test”,先用 `check`。
|
|
174
|
+
|
|
175
|
+
## 什么时候需要 `upgrade`
|
|
176
|
+
|
|
177
|
+
下面这些情况,优先考虑 `repo upgrade`:
|
|
178
|
+
|
|
179
|
+
- 文档里的根脚本在你仓库里没有
|
|
180
|
+
- 默认的 Husky / lint-staged / config 资产缺失
|
|
181
|
+
- 模板最近更新过,而你的仓库还是旧结构
|
|
182
|
+
- 你希望重新同步推荐默认值
|
|
183
|
+
|
|
184
|
+
## 一个实用排查顺序
|
|
185
|
+
|
|
186
|
+
大多数问题按这个顺序处理最省时间:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
pnpm install
|
|
190
|
+
pnpm doctor
|
|
191
|
+
pnpm exec repo upgrade
|
|
192
|
+
pnpm doctor
|
|
193
|
+
pnpm check
|
|
194
|
+
pnpm build
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
思路是:
|
|
198
|
+
|
|
199
|
+
1. 先把依赖装齐
|
|
200
|
+
2. 先修仓库架子问题
|
|
201
|
+
3. 再看当前改动的校验问题
|
|
202
|
+
|
|
203
|
+
## 还有问题时看哪里
|
|
204
|
+
|
|
205
|
+
- 日常命令边界不清楚:[命令速查](./commands.md)
|
|
206
|
+
- 不确定仓库怎么管理:[如何管理 monorepo](./manage.md)
|
|
207
|
+
- 发包问题:[发包与变更日志](./publish.md)
|
|
@@ -23,17 +23,17 @@
|
|
|
23
23
|
"typecheck": "tsc -p tsconfig.json"
|
|
24
24
|
},
|
|
25
25
|
"dependencies": {
|
|
26
|
-
"vue": "^3.5.
|
|
26
|
+
"vue": "^3.5.33"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@braintree/sanitize-url": "^7.1.2",
|
|
30
|
-
"@tailwindcss/vite": "^4.2.
|
|
31
|
-
"cytoscape": "^3.33.
|
|
30
|
+
"@tailwindcss/vite": "^4.2.4",
|
|
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
|
-
"mermaid": "^11.
|
|
36
|
-
"tailwindcss": "^4.2.
|
|
35
|
+
"mermaid": "^11.14.0",
|
|
36
|
+
"tailwindcss": "^4.2.4",
|
|
37
37
|
"vitepress": "^1.6.4",
|
|
38
38
|
"vitepress-plugin-mermaid": "^2.0.17"
|
|
39
39
|
}
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
|
|
32
32
|
### 语言与打包
|
|
33
33
|
|
|
34
|
-
我选择使用纯 `TypeScript`
|
|
34
|
+
我选择使用纯 `TypeScript` 来编写所有类库项目,并统一使用 `tsdown` 进行打包,默认输出格式为 `cjs` 和 `esm`,并利用 `package.json` 中的 `exports` 字段进行分发。
|
|
35
35
|
|
|
36
36
|
### 直接调试
|
|
37
37
|
|
|
@@ -15,8 +15,8 @@
|
|
|
15
15
|
在提交前运行 `prettier --write .`,确保代码风格一致。
|
|
16
16
|
2. **Lint 检查**
|
|
17
17
|
在 `pre-commit` 时执行 `eslint`,防止有 lint 错误的代码被提交。
|
|
18
|
-
3.
|
|
19
|
-
在 `pre-push`
|
|
18
|
+
3. **推送前执行整仓校验**
|
|
19
|
+
在 `pre-push` 时执行整仓 `lint`、`typecheck`,并按需补跑 `build`、`test`、`tsd`,防止未通过校验的代码被推送。
|
|
20
20
|
4. **Commit 信息校验**
|
|
21
21
|
在 `commit-msg` hook 中使用 [commitlint](https://github.com/conventional-changelog/commitlint) 强制提交信息符合规范(如 Conventional Commits)。
|
|
22
22
|
|
|
@@ -101,6 +101,11 @@ npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"
|
|
|
101
101
|
npx lint-staged
|
|
102
102
|
```
|
|
103
103
|
|
|
104
|
+
在本仓库默认实现里,`pre-commit` 和 `pre-push` 的职责拆分是:
|
|
105
|
+
|
|
106
|
+
- `pre-commit`:只针对 staged 文件执行 `eslint`、`stylelint` 和 workspace `typecheck`
|
|
107
|
+
- `pre-push`:强制执行整仓 `pnpm lint`、`pnpm typecheck`,并根据改动范围补跑 `build`、`test`、`tsd`
|
|
108
|
+
|
|
104
109
|
## 总结
|
|
105
110
|
|
|
106
111
|
- **Husky** 是一个 Git hooks 工具,用来在 commit、push 等阶段运行脚本。
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
|
|
10
10
|
- Husky 负责触发 Git hooks(比如 `pre-commit`)。
|
|
11
11
|
- lint-staged 负责只对 **本次提交涉及的文件** 进行检查和修复。
|
|
12
|
+
- 在本仓库默认配置里,`ts` / `tsx` / `mts` / `cts` / `vue` 文件还会继续触发对应 workspace 的 `typecheck`。
|
|
12
13
|
|
|
13
14
|
这样就避免了对整个项目运行 lint/format,节省时间。
|
|
14
15
|
|
|
@@ -19,7 +20,7 @@
|
|
|
19
20
|
- **常见场景**:
|
|
20
21
|
- 运行 ESLint 自动修复:`eslint --fix`
|
|
21
22
|
- 运行 Prettier 格式化:`prettier --write`
|
|
22
|
-
- 运行
|
|
23
|
+
- 运行 workspace 级类型检查:Vue 项目通常是 `vue-tsc -b`,TS 项目通常是 `tsc -p tsconfig.json`
|
|
23
24
|
- 优化图片、转换 Markdown 等自定义脚本
|
|
24
25
|
|
|
25
26
|
## 3. 如何使用 lint-staged?
|
|
@@ -56,6 +57,18 @@ npx lint-staged
|
|
|
56
57
|
|
|
57
58
|
这样在提交时,lint-staged 会自动处理已暂存的文件。
|
|
58
59
|
|
|
60
|
+
本仓库默认生成的规则更接近下面这种形式:
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
export default {
|
|
64
|
+
'*.{js,jsx,mjs,ts,tsx,mts,cts}': ['eslint --fix'],
|
|
65
|
+
'*.vue': ['eslint --fix', 'stylelint --fix --allow-empty-input'],
|
|
66
|
+
'*.{ts,tsx,mts,cts,vue}': files => `pnpm exec repoctl verify staged-typecheck ${files.join(' ')}`,
|
|
67
|
+
'*.{json,md,mdx,html,yml,yaml}': ['eslint --fix'],
|
|
68
|
+
'*.{css,scss,sass,less}': ['stylelint --fix --allow-empty-input'],
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
59
72
|
## 4. 示例工作流
|
|
60
73
|
|
|
61
74
|
假设你改了两个文件:
|
|
@@ -77,3 +90,4 @@ npx lint-staged
|
|
|
77
90
|
- **lint-staged = 只在 staged 文件上运行 lint/脚本的工具**。
|
|
78
91
|
- 优点:快、精准,避免全量检查。
|
|
79
92
|
- 常和 **Husky** 搭配,用于 `pre-commit`。
|
|
93
|
+
- 在 monorepo 里很适合把 ESLint、Stylelint 和 workspace `typecheck` 串起来。
|
|
@@ -1,12 +1,8 @@
|
|
|
1
1
|
/* eslint-disable no-console */
|
|
2
|
-
// import c from 'chalk'
|
|
3
|
-
// const c = require('chalk')
|
|
4
2
|
const { sayHello } = require('icebreaker-npm-basic-package')
|
|
5
3
|
const { sayHello: sayHelloCjs } = require('icebreaker-npm-basic-package-multiple-exports')
|
|
4
|
+
const pc = require('picocolors')
|
|
6
5
|
|
|
7
6
|
sayHello()
|
|
8
7
|
sayHelloCjs()
|
|
9
|
-
|
|
10
|
-
import('chalk').then(({ default: c }) => {
|
|
11
|
-
console.log(c.green('Hello World!'))
|
|
12
|
-
})
|
|
8
|
+
console.log(pc.green('Hello World!'))
|
|
@@ -9,22 +9,16 @@
|
|
|
9
9
|
"version": "1.0.0",
|
|
10
10
|
"license": "ISC",
|
|
11
11
|
"dependencies": {
|
|
12
|
-
"chalk": "^5.6.2",
|
|
13
12
|
"icebreaker-npm-basic-package": "^1.0.5",
|
|
14
|
-
"icebreaker-npm-basic-package-multiple-exports": "^0.0.0"
|
|
13
|
+
"icebreaker-npm-basic-package-multiple-exports": "^0.0.0",
|
|
14
|
+
"picocolors": "^1.1.1"
|
|
15
15
|
}
|
|
16
16
|
},
|
|
17
|
-
"node_modules/
|
|
18
|
-
"version": "
|
|
19
|
-
"resolved": "https://registry.npmjs.org/
|
|
20
|
-
"integrity": "sha512-
|
|
21
|
-
"license": "
|
|
22
|
-
"engines": {
|
|
23
|
-
"node": "^12.17.0 || ^14.13 || >=16.0.0"
|
|
24
|
-
},
|
|
25
|
-
"funding": {
|
|
26
|
-
"url": "https://github.com/chalk/chalk?sponsor=1"
|
|
27
|
-
}
|
|
17
|
+
"node_modules/picocolors": {
|
|
18
|
+
"version": "1.1.1",
|
|
19
|
+
"resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
|
|
20
|
+
"integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
|
|
21
|
+
"license": "ISC"
|
|
28
22
|
},
|
|
29
23
|
"node_modules/icebreaker-npm-basic-package": {
|
|
30
24
|
"version": "1.0.5",
|
|
@@ -13,8 +13,8 @@
|
|
|
13
13
|
"cjs": "node cjs.cjs"
|
|
14
14
|
},
|
|
15
15
|
"dependencies": {
|
|
16
|
-
"chalk": "^5.6.2",
|
|
17
16
|
"icebreaker-npm-basic-package": "^1.0.5",
|
|
18
|
-
"icebreaker-npm-basic-package-multiple-exports": "^0.0.0"
|
|
17
|
+
"icebreaker-npm-basic-package-multiple-exports": "^0.0.0",
|
|
18
|
+
"picocolors": "^1.1.1"
|
|
19
19
|
}
|
|
20
20
|
}
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/* eslint-disable no-console */
|
|
2
|
-
import c from 'chalk'
|
|
3
2
|
import { sayHello } from 'icebreaker-npm-basic-package'
|
|
4
3
|
import { sayHello as sayHello2 } from 'icebreaker-npm-basic-package-multiple-exports'
|
|
4
|
+
import pc from 'picocolors'
|
|
5
5
|
|
|
6
6
|
sayHello()
|
|
7
7
|
sayHello2()
|
|
8
|
-
console.log(
|
|
8
|
+
console.log(pc.green('Hello World!'))
|