react-19-component-scaffolder

React 19 组件脚手架生成器

根据参数化模板生成 React 19/19.2 组件、页面、Hooks 和配套文件。每个模板都会强制遵循同级 react 技能中规定的模式——将 ref 作为常规属性（绝不使用 forwardRef）、直接将 Context 渲染为 provider（绝不使用 .Provider）、使用 useActionState + useFormStatus 处理表单操作、内联文档元数据、使用 useSyncExternalStore 订阅外部状态，以及符合 YMNNAE 的 Hook 函数体。

适用场景

• 创建新的 React 组件（Server、Client 或未指定——默认使用 Server）
• 在 React 19 应用中添加新路由／页面
• 构建需要渐进增强、乐观 UI 或待处理状态的表单
• 创建包含状态与 dispatch 拆分的新 Context provider
• 编写订阅外部状态或封装异步工作的自定义 Hook
• 使用类型化 reducer 对复杂状态建模
• 添加文档元数据（<title>、<meta>、<link>）或资源提示（preload、preconnect、prefetchDNS）
• 用户说出“scaffold”“boilerplate”“generate”“new component”“new page”“new hook”，或提及任何一种模板类型

可用模板

所有文件名均为 kebab-case；导出的 React 标识符（{Name}、use{Name}）采用 PascalCase／camelCase。

#	模板	用途	生成的文件
1	function-component	通用可复用组件（适用于 Server 或 Client）	{name-kebab}.tsx、{name-kebab}.test.tsx
2	server-component-page	包含服务端数据获取、Suspense 和元数据的路由页面	page.tsx
3	client-island	嵌套在服务端页面中的 'use client' 交互部分	{name-kebab}-island.tsx、{name-kebab}-island.test.tsx
4	form-action	使用 useActionState + Zod schema + 服务端 action 的变更表单	{name-kebab}-form.tsx、actions.ts、schema.ts
5	context-provider	拆分 state／dispatch 并提供访问器 Hook 的共享状态	{name-kebab}-context.tsx
6	custom-hook	符合 YMNNAE 的 Hook（外部订阅或组合式 effect）	use-{name-kebab}.ts、use-{name-kebab}.test.ts
7	reducer	使用判别联合类型 action 和穷尽式 switch 的类型化 reducer	{name-kebab}-reducer.ts、{name-kebab}-reducer.test.ts
8	head-and-hints	为首屏资源添加文档元数据和资源提示	{name-kebab}-head.tsx

使用方法

1. 确定匹配用户需求的模板。如果需求不明确，请提问。对于未指定类型的“给我做个组件”请求，默认使用 function-component。
2. 读取模板：assets/templates/{name}.template。
3. 阅读相关约定：references/conventions.md——每个模板生成的代码都会遵循这些约定。
4. 收集参数（见下方“参数”）。只有无法从上下文推断的参数才向用户询问。
5. 替换占位符。模板中的每个占位符都用 {大括号} 括起。空占位符（例如没有额外 Hook 时的 {additional_hooks}）会替换为空字符串。
6. 使用 Write 工具写入每个输出文件。路径约定请参见 config.json（module_path、route_path）。
7. 说明所遵循的约定，让用户了解生成代码采用这些写法的原因（例如：“我将 ref 作为属性而不是使用 forwardRef，因为……”）。

参数

常见参数（大多数模板都接受）：

参数	必填	默认值	描述
name	是	—	PascalCase 格式的组件 / hook / reducer 标识符（hook 和 reducer 使用 camelCase）。脚手架会自动生成 file_name（kebab-case）和 name_kebab。
module_path	否	src/components（或来自 config.json）	项目根目录下用于存放生成文件的目录
props	否	[]	{name, type, required} 列表，生成后作为 props 接口
with_test	否	true	生成对应的 *.test.tsx / *.test.ts 文件
with_ref	否	false	在 props 中添加 ref?: Ref<T>（模板 1 和 3）

模板专属参数记录在各模板开头的注释中。

设置

首次使用时，请在 config.json 中填入项目专属路径，确保生成的文件放在正确的位置。默认路径假设项目采用标准的 src/ 根目录。若要交互式覆盖默认值：

• module_path — 组件所在位置（例如 src/components、app/_components）
• route_path — Server Component 页面所在位置（例如 app/、src/routes/）
• hooks_path — 自定义 hook 所在位置（例如 src/hooks）
• test_runner — vitest（默认）或 jest（会更改测试模板中的导入语句）

规范化现有代码（多文件重构）

当用户要求规范化、现代化或对齐现有组件，使其符合此技能的约定，且涉及一个或多个文件时（而不是生成新代码），请改用 references/_conform-algorithm.md，不要逐个文件处理。

该文档中有两条不可妥协的原则：

1. 判断优先于 grep。 每项约定都对应一个语法标记（forwardRef、<Context.Provider>、react-helmet、onSubmit=、react-dom/test-utils）。grep 能找到简单情况，但会漏掉经过伪装的情况——例如作者为了避开 forwardRef 而手动传递 callback ref、自定义的 useState({ pending, error })（本质上是 useActionState，只是没有使用这个名称），以及手写的 document.title。仅使用 grep 清点代码并在事后检查是否完整，切勿将其作为主要检测手段。
2. 按约定处理，而非按文件处理。 先加载所有目标文件，然后按优先级一次处理一项约定，并覆盖所有文件（先处理 ref/context/forms，最后处理命名/导入）。报告按约定分组，突出显示跨文件的关联问题。

对于全新脚手架，无需遵循此流程——直接使用模板。

此技能拒绝生成的 React 19 模式

• forwardRef(...) 包装器——改为生成 function Name({ ref, ...props })
• <Context.Provider value={...}>——改为生成 <Context value={...}>
• useFormState——改为生成 useActionState
• 用于修改操作的 onSubmit 处理器——改为生成 <form action={serverAction}>
• 不带参数的 useRef<T>()——改为生成 useRef<T>(null)
• 用于派生状态、通知父级或状态变化后执行 POST 的 useEffect——完全拒绝生成（参见 conventions: State derivation）
• react-dom/test-utils——改为生成 import { act } from '@testing-library/react'
• 手动编写的 <link rel="preload"> JSX——改为生成来自 react-dom 的 preload()
• react-helmet / react-helmet-async——改为生成内联 <title>/<meta>/<link>

注意事项

参见 gotchas.md。首次发布时内容为空；随着使用此技能，注意事项会逐渐累积。

相关技能

• react — 权威的 React 19 最佳实践精要（44 条规则）。此技能中的模板会生成符合这些规则的代码。