@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.
Files changed (79) hide show
  1. package/README.md +12 -0
  2. package/assets/.changeset/config.json +7 -2
  3. package/assets/.github/workflows/ci.yml +8 -2
  4. package/assets/.github/workflows/release.yml +2 -2
  5. package/assets/.husky/commit-msg +1 -1
  6. package/assets/.husky/pre-commit +1 -1
  7. package/assets/.husky/pre-push +5 -0
  8. package/assets/AGENTS.md +8 -7
  9. package/assets/commitlint.config.ts +2 -2
  10. package/assets/eslint.config.js +2 -6
  11. package/assets/lint-staged.config.js +3 -0
  12. package/assets/package.json +39 -28
  13. package/assets/repoctl.config.ts +68 -0
  14. package/assets/stylelint.config.js +2 -2
  15. package/assets/tooling/ensure-tooling-built.mjs +24 -0
  16. package/assets/tooling/load-tooling-module.mjs +71 -0
  17. package/assets/tsconfig.json +1 -49
  18. package/assets/turbo.json +17 -6
  19. package/assets/vitest.config.ts +2 -125
  20. package/assets-data.mjs +4 -2
  21. package/dist/index.d.mts +22 -1
  22. package/dist/index.mjs +114 -30
  23. package/package.json +12 -8
  24. package/template-data.mjs +48 -8
  25. package/templates/client/eslint.config.js +6 -4
  26. package/templates/client/package.json +22 -22
  27. package/templates/client/vite.config.ts +4 -3
  28. package/templates/client/wrangler.jsonc +1 -6
  29. package/templates/server/package.json +4 -4
  30. package/templates/server/src/app.ts +4 -4
  31. package/templates/server/tsconfig.json +1 -2
  32. package/templates/server/vitest.config.ts +6 -5
  33. package/templates/server/wrangler.jsonc +1 -6
  34. package/templates/tsdown/package.json +2 -1
  35. package/templates/tsdown/test-d/index.test-d.ts +5 -0
  36. package/templates/tsdown/tsconfig.json +1 -2
  37. package/templates/tsdown/vitest.config.ts +6 -5
  38. package/templates/vitepress/.vitepress/config.ts +34 -36
  39. package/templates/vitepress/getting-started.md +243 -0
  40. package/templates/vitepress/gitignore +2 -1
  41. package/templates/vitepress/index.md +144 -79
  42. package/templates/vitepress/monorepo/commands.md +281 -0
  43. package/templates/vitepress/monorepo/index.md +103 -34
  44. package/templates/vitepress/monorepo/manage.md +181 -80
  45. package/templates/vitepress/monorepo/publish.md +128 -57
  46. package/templates/vitepress/monorepo/templates.md +67 -0
  47. package/templates/vitepress/monorepo/troubleshooting.md +207 -0
  48. package/templates/vitepress/package.json +5 -5
  49. package/templates/vitepress/thinking.md +1 -1
  50. package/templates/vitepress/tools/husky.md +7 -2
  51. package/templates/vitepress/tools/lint-staged.md +15 -1
  52. package/templates/vitepress/why/examples/usage-cjs/index.js +2 -6
  53. package/templates/vitepress/why/examples/usage-cjs/package-lock.json +7 -13
  54. package/templates/vitepress/why/examples/usage-cjs/package.json +2 -2
  55. package/templates/vitepress/why/examples/usage-esm/index.js +2 -2
  56. package/templates/vitepress/why/examples/usage-esm/package-lock.json +7 -13
  57. package/templates/vitepress/why/examples/usage-esm/package.json +2 -2
  58. package/templates/vitepress/why/modern/bundlers.md +8 -46
  59. package/templates/vue-lib/eslint.config.js +6 -4
  60. package/templates/vue-lib/package.json +17 -12
  61. package/templates/vue-lib/test-d/index.test-d.ts +6 -0
  62. package/templates/vue-lib/tsconfig.test.json +1 -1
  63. package/templates/vue-lib/vitest.config.ts +8 -5
  64. package/assets/monorepo.config.ts +0 -22
  65. package/assets/nano-staged.js +0 -18
  66. package/templates/tsup/build.config.ts +0 -24
  67. package/templates/tsup/package.json +0 -49
  68. package/templates/tsup/src/index.ts +0 -12
  69. package/templates/tsup/test/index.test.ts +0 -18
  70. package/templates/tsup/tsconfig.json +0 -15
  71. package/templates/tsup/tsup.config.ts +0 -18
  72. package/templates/tsup/vitest.config.ts +0 -15
  73. package/templates/unbuild/build.config.ts +0 -24
  74. package/templates/unbuild/package.json +0 -49
  75. package/templates/unbuild/src/index.ts +0 -9
  76. package/templates/unbuild/src/utils.ts +0 -5
  77. package/templates/unbuild/test/index.test.ts +0 -18
  78. package/templates/unbuild/tsconfig.json +0 -15
  79. package/templates/unbuild/vitest.config.ts +0 -15
@@ -1,42 +1,71 @@
1
1
  # monorepo 发包与变更日志
2
2
 
3
- 本模板推荐使用 [`changesets`](https://github.com/changesets/changesets) 管理版本、生成 `CHANGELOG` 并发布 npm 包。它针对 monorepo 场景设计,维护活跃,易于与 CI/CD 集成。
3
+ 这套模板默认推荐用 `changesets` 管理版本和 changelog。原因不是“它很流行”,而是它对 monorepo 的工作方式最顺手:
4
4
 
5
- ## 为什么选 changesets?
5
+ - 变更是按包记录的
6
+ - 版本升级能自动联动内部依赖
7
+ - changelog 可以稳定产出
8
+ - 很容易接到 CI 里
6
9
 
7
- | 场景 | changesets 能力 |
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
- ### 1. 初始化
19
+ 对应到命令,一般是:
19
20
 
20
21
  ```bash
21
- pnpm add -D @changesets/cli
22
- pnpm changeset init
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
- 生成 `.changeset/` 目录,用于存放配置与变更记录。
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. 指定版本类型(`patch` / `minor` / `major`)。
37
- 3. 填写 changelog 描述。
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. 升级版本并生成 changelog
80
+ ### 3. 合并前看一眼影响面
52
81
 
53
- ```bash
54
- pnpm changeset version
55
- ```
82
+ changeset 文件本身就是最便宜的“发布预告”。代码评审时顺手看一下,通常就能避免:
56
83
 
57
- 命令会自动:
84
+ - 漏记某个包
85
+ - 版本类型选错
86
+ - changelog 写得太含糊
58
87
 
59
- - 更新受影响包的 `package.json` 版本。
60
- - 调整内部依赖引用。
61
- - 为每个包写入或追加 `CHANGELOG.md`。
88
+ ## 发布阶段怎么做
62
89
 
63
- ### 4. 发布到 npm
90
+ ### 手动流程
64
91
 
65
92
  ```bash
66
- pnpm changeset publish
93
+ pnpm changeset version
94
+ pnpm publish-packages
67
95
  ```
68
96
 
69
- changesets 会只发布有改动的包,并按照依赖顺序执行。
97
+ `changeset version` 会做这些事:
98
+
99
+ - 更新受影响包的版本号
100
+ - 调整内部依赖版本
101
+ - 生成或更新每个包的 `CHANGELOG.md`
102
+
103
+ ### CI 自动流程
70
104
 
71
- ### 5. GitHub Actions 自动化(可选)
105
+ 模板推荐结合 `changesets/action`。
72
106
 
73
- 结合 `changesets/action` 实现自动创建发布 PR 或直接发布:
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
- `pnpm publish-packages` 为模板内脚本,可替换为自定义构建+发布流程。
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
- > 说明:npm 现行 token 默认 90 天过期,推荐在 CI 中使用 OIDC(如上)动态获取 `NODE_AUTH_TOKEN`,无需手动传入 `NPM_TOKEN`。若使用自托管或其他 CI,需要确保工作流具备 `id-token: write` 权限。
196
+ ### 如何跳过某个包的发布?
119
197
 
120
- ## 与其他方案对比
198
+ - 在 changeset 里不要勾选它
199
+ - 或者把它标记为 `private: true`
121
200
 
122
- | 能力 / 工具 | changesets | lerna 经典模式 | 手写脚本 |
123
- | -------------- | ---------- | -------------- | -------- |
124
- | 支持多包 | ✅ | ✅ | ❌ |
125
- | 自动 changelog | ✅ | 部分支持 | ❌ |
126
- | 逐条记录变更 | ✅ | ❌ | ❌ |
127
- | 维护活跃度 | 高 | 低 | 需自养 |
128
- | CI/CD 集成 | 简单 | 相对繁琐 | 完全手工 |
201
+ ### 为什么要在 PR 阶段就看 changeset?
129
202
 
130
- ## 常见问题 FAQ
203
+ 因为它本质上是在回答一个非常具体的问题:
131
204
 
132
- - **是否可与 `monorepo.config.ts` 联动?** 配置文件主要用于 CLI 行为定制,发布流程仍由 changesets 主导,两者互不冲突。
133
- - **为何 `CHANGELOG` 没生成?** 确认是否执行了 `pnpm changeset version` 并提交了 `.changeset` 文件。
134
- - **如何避免发布某些包?** 在创建 changeset 时不勾选即可,或将包标记为 `private: true`。
205
+ “这次改动准备怎么影响发布面?”
135
206
 
136
- ## 相关资源
207
+ 这个问题越早看,越不容易在合并后补救。
137
208
 
138
- - [changesets 官方文档](https://github.com/changesets/changesets)
139
- - [模板中的发布工作流示例](https://github.com/sonofmagic/monorepo-template/blob/main/.github/workflows/release.yml)
140
- - [管理指南:pnpm + Turborepo + monorepo.config](./manage.md)
209
+ ## 继续阅读
141
210
 
142
- > 小提示:在 PR 合并前先执行 `pnpm changeset version` 并提交结果,可以在代码审查阶段提前暴露发布影响,避免遗漏。
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.30"
26
+ "vue": "^3.5.33"
27
27
  },
28
28
  "devDependencies": {
29
29
  "@braintree/sanitize-url": "^7.1.2",
30
- "@tailwindcss/vite": "^4.2.1",
31
- "cytoscape": "^3.33.1",
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.13.0",
36
- "tailwindcss": "^4.2.1",
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` 来编写所有类库项目,并使用 `tsup` / `unbuild` 进行打包,默认输出格式为 `cjs` 和 `esm`,并利用 `package.json` 中的 `exports` 字段进行分发。
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` 时执行 `npm test`,防止未通过测试的代码被推送。
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
- - 运行 TypeScript 编译检查:`tsc --noEmit`
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/chalk": {
18
- "version": "5.6.2",
19
- "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz",
20
- "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==",
21
- "license": "MIT",
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(c.green('Hello World!'))
8
+ console.log(pc.green('Hello World!'))