nuqs-scaffolder

nuqs 脚手架

根据一份规范生成一组完整的 nuqs 文件。此技能由模板驱动——读取规范、复制模板并替换占位符。无需构建步骤，也无需代码生成运行时；模板本身就是产物。

何时使用

在以下情况使用此技能：

• 新的 Next.js 页面需要由 URL 驱动的筛选、分页、搜索或排序状态
• 要将现有页面临时编写的 useState 筛选逻辑统一迁移到 nuqs
• 代码审查经常发现客户端和服务端的解析器定义不一致——此技能会让这种不一致在机制上无法发生，因为两端都会导入同一份映射
• 用户要求“为这些查询参数添加 Standard Schema 验证，以供 tRPC 使用”——生成的 searchParams.server.ts 已经导出了该 schema

如果代码库使用的是旧版 nuqs 模式，请先运行 nuqs-codemod-runner 技能。

使用方法

1. 读取或创建规范。 从 assets/templates/spec.template.json 开始，填写 name、module 和 params。请参阅下方的“规范格式”。
2. 渲染每个模板，将占位符替换为从规范中得出的值。
3. 将渲染后的每个文件写入 根据 config.json 计算出的路径（可按调用覆盖）。
4. 提交前向用户展示差异——此技能不会修改现有文件；如果目标路径已存在，请先询问是否覆盖。

由 Agent 负责渲染——Claude 就是模板引擎。每个模板都带有标记（/*= ... =*/），用于指明占位符位置并说明替换规则。

规范格式

{
  "name":   "Search",                    // PascalCase — drives the exported symbol names
  "module": "search",                    // kebab-case — drives file paths and the "module" folder

  "params": {
    "q":          { "type": "string",                                    "default": "" },
    "page":       { "type": "integer",                                   "default": 1 },
    "limit":      { "type": "integer",                                   "default": 10 },
    "categories": { "type": "array-of-string-native",                    "default": [] },
    "sort":       { "type": "string-literal", "values": ["asc","desc"],  "default": "asc" },
    "minPrice":   { "type": "float",                                     "default": null },
    "lastSeen":   { "type": "iso-date",                                  "default": null }
  }
}

支持的 type 值

type	使用的解析器	说明
string	parseAsString
integer	parseAsInteger
float	parseAsFloat
boolean	parseAsBoolean
iso-date	parseAsIsoDate	仅日期
iso-date-time	parseAsIsoDateTime	日期和时间
timestamp	parseAsTimestamp	自纪元起的毫秒数
hex	parseAsHex	数值，URL 中为十六进制形式
index	parseAsIndex	代码中从 0 开始，URL 中从 1 开始
array-of-string	parseAsArrayOf(parseAsString)	?tags=a,b,c
array-of-string-native	parseAsNativeArrayOf(parseAsString)	?tag=a&tag=b — 需要 nuqs ≥ 2.7
string-literal	parseAsStringLiteral(values)	需要 values: string[]
number-literal	parseAsNumberLiteral(values)	需要 values: number[]
json	parseAsJson(SchemaName.parse)	生成 Zod schema 占位文件；单独标记 default

如果 default 为 null，该参数可为 null；否则模板会使用 .withDefault(...)。

可用模板

模板	渲染到（默认）	加载时机
searchParams.ts.template	lib/{module}-search-params.ts	始终
searchParams.server.ts.template	lib/{module}-search-params.server.ts	始终
filters.tsx.template	components/{module}/{name}-filters.tsx	始终
filters.test.tsx.template	components/{module}/{name}-filters.test.tsx	当 config.generate_tests 为 true 时
spec.json.template	任意位置 — 提供给用户的起始模板	首次运行提示时

模板文件以 .template 结尾，这样编辑器就不会对占位符标记应用语法高亮——原始扩展名保留为 .template 之前的后缀，因此仍可一眼看出渲染后文件的类型。

路径可在 config.json 中配置——可以覆盖 glob 模式、文件命名风格（kebab 或 PascalCase），以及是否生成测试。

占位符参考

所有模板都使用相同的占位符语法。Agent 会一次性替换它们：

占位符	来源	示例
__NAME__	spec.name	Search
__name__	spec.name 的 camelCase 形式	search
__module__	spec.module	search
/*= PARSERS =*/	遍历 spec.params → key: parseAsXxx.withDefault(...) 行	参见模板
/*= COMPONENT_FIELDS =*/	遍历 spec.params → 每种类型对应一个输入框/选择框	参见模板
/*= TEST_CASES =*/	遍历 spec.params → 每个默认值对应一条断言	参见模板
/*= NULLABLE_IMPORTS =*/	如果任何参数可为空，则添加 Nullable 辅助工具导入	条件性添加
/*= ZOD_SCHEMAS =*/	对于 json 类型的参数，生成一个 Zod 模式存根	条件性添加

/*= ... =*/ 标记是给 Agent 的指令，不是要按字面进行的替换。请将整个标记（包括 /*= =*/ 分隔符）替换为展开后的内容。

约定

阅读 references/conventions.md，了解：

• 文件命名（kebab-case）及其原因
• 导入顺序（外部 → nuqs → 内部 → 相对路径）及其原因
• 为什么服务器文件是同级文件，而不放在 app/ 内
• 何时应分叉模板（通常不应该）

设置

config.json 已预先填入合理的 Next.js App Router 默认值。只有当你的仓库采用不同约定时才覆盖：

{
  "lib_dir": "lib",
  "components_dir": "components",
  "generate_tests": true,
  "test_runner": "vitest"
}

首次使用时，如果未提供规范文件，Agent 应通过 AskUserQuestion 向用户询问规范。

相关技能

• nuqs — 这些模板所遵循的最佳实践参考。阅读它，了解模板为何采用这种结构。
• nuqs-codemod-runner — 如果要将现有页面从 pre-v2.5 nuqs 迁移过来，请在使用此技能前运行。

注意事项

关于使用过程中发现的边缘情况，请参见 gotchas.md。