content/docs/guide/plugins.md 的插件骨架:step 5 的 vite.config.ts import 了 @vitejs/plugin-react,step 6 的 devDependencies 从未声明它(照抄即构建失败) #4961

越界发现,记录于 #3855(该页示例 package.json 的 vite/typescript 版本化石)实施期间 —— 为了判定「devDependencies 这一块该锚到哪」而逐行读这份骨架时扫到的。#3855 的完成范围限定在那两个版本值 + 把该拼写纳入 #3711 的版本声称门,这一条是块内容的缺项而非版本值,故只记录。

事实(对 origin/main @ 1b21b1aaa 实测)

content/docs/guide/plugins.md 的 "Creating Custom Plugins" 是一份编号步骤的脚手架教程,读者按 1→6 顺序照抄。其中两步互相矛盾:

• Step 5 "Configure Build"(:340)—— 给出的 vite.config.ts 第三行就是
  import react from '@vitejs/plugin-react',并在 plugins: [react()] 里用掉它。
• Step 6 "Add Package.json"(:397-403)—— 给出的 devDependencies 是
  @object-ui/components / @object-ui/core / @object-ui/types(均 workspace:*)、
  typescript、vite。@vitejs/plugin-react 不在其中,全页仅 :340 那一次 import 提到过它。

照这两步做出来的包,pnpm build 在解析 vite.config.ts 的第三行就失败 —— 导入了一个从未安装的包。

仓内锚点(19 个 packages/plugin-*/package.json 全部一致):

也就是说锚是现成且一致的,不需要任何判断:骨架缺的正是仓内每个 plugin 包都声明的那一条。

与已关闭的两条同形先例

• create-plugin 生成的插件跑不了自己的测试:模板写入 test 文件与 test 脚本,却没在 devDependencies 里声明 @testing-library/react 与 jest-dom #3716 —— create-plugin 生成的插件写入了 test 文件与 test 脚本,却没在 devDependencies 里声明 @testing-library/react 与 jest-dom。完全同一形状(产物声明了一个用法,却没声明它的依赖),只是发生在生成器面。
• create-plugin 生成产物的 build 侧 devDependencies 内部不一致且落后仓库工具链 1–2 个 major:@vitejs/plugin-react ^4.2.1 的 peer 结构性无法被 vite ^7.3.1 满足 #3742 —— 同一族的 build 侧 devDependencies 内部不一致(@vitejs/plugin-react ^4.2.1 的 peer 结构性无法被 vite ^7.3.1 满足),也在生成器面。

两条都已修且都在 packages/create-plugin / packages/cli,手写文档面这一份没被一起过一遍 —— 生成器和这页教的是同一件事,却各自维护。

影响

读者照抄这份编号教程起新插件,在 step 5/6 之后第一次 pnpm build 即失败。与 #3855 的「版本区间脱钩,踩到时表现为『我的插件构建不出来』」是同一种用户体验,但更直接:那边是版本不匹配,这边是包根本没装。

修法(顺带说明它现在也会被门守住)

在 step 6 的 devDependencies 里加 "@vitejs/plugin-react": "^6.0.5"。

注意这会引入一处新的版本字面量,于是 #3711 的棘轮门(scripts/__tests__/doc-version-claims.test.ts)会立刻变红,要求给它一条 KNOWN_CLAIMS 条目 —— 这正是该门的设计。#3855 落地后这条条目的自然写法已经有了机械支撑:kind: 'anchored' + skeletonDep: '@vitejs/plugin-react',新增的 plugin-skeleton 断言会自动把该行的区间与 19 个 plugin 清单比对,不需要再写新机制。所以这一单的成本基本只有那一行文档 + 一条条目。

不是 Blocked-by: #3855 —— 这一条独立可做;#3855 只是让它的门禁条目更便宜。若在 #3855 合并前动手,skeletonDep 还不存在,按当时的 sample/anchored 写法记账即可。

顺带核过、不用动的两处

• 骨架的 peerDependencies 写 react/react-dom 为 ^18.0.0 || ^19.0.0,与仓内平台包 peer 面一致(packages/cli 的 createTempAppWithRouting 生成的 app import 了未声明的 lucide-react,且其工具链区间落后仓内一到三个 major #3827 / content/docs/guide/plugins.md 的示例 package.json 里 vite ^5.0.0 / typescript ^5.0.0 落后仓内三个与一个 major(#3709 同族化石,文档面最后两处) #3855 同一判据:peer 说「能接受什么」,与「本仓装哪个」是两回事)。
• 骨架没有 vite-plugin-dts,而仓内 19 个 plugin 包都有 —— 但这不是缺项:骨架的 build 脚本是 vite build && tsc --emitDeclarationOnly,声明文件由 tsc 自己出,不经 dts 插件。两种写法都自洽,别照着仓内清单机械补齐。

Generated by Claude Code