nuqs-scaffolder — скилл для Claude Code: URL-фильтры в Next.js
Скилл nuqs-scaffolder собирает из одного JSON-описания четыре файла для фильтров в URL на Next.js: карту парсеров, серверный загрузчик, клиентский компонент и тест.
MIT 145 установок ★ 227 обновлён 2026-08-15
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a claude-codeЧто делает nuqs-scaffolder
Скилл берёт JSON-описание страницы (name, module, params) и рендерит по шаблонам четыре файла: карту парсеров lib/{module}-search-params.ts, серверный вариант рядом с ней, клиентский компонент с фильтрами и тест Vitest. Клиент и сервер импортируют одну и ту же карту, поэтому парсеры не расходятся.
Шаблоны лежат в assets/templates и размечены маркерами вида /*= PARSERS =*/. Агент сам разворачивает маркеры в строки parseAsXxx.withDefault(...), поля формы и проверки значений по умолчанию. Сборки и кодогенератора нет. Поддерживаются string, integer, float, boolean, iso-date, timestamp, string-literal, массивы и json; для json появится заготовка Zod-схемы. Каталоги и выпуск тестов задаёт config.json.
Один тип упирается в версию библиотеки: array-of-string-native требует nuqs 2.7 или новее, иначе берите array-of-string с запятой в URL. Существующие файлы скилл не перезаписывает, а спрашивает. Если в проекте старый стиль nuqs, сначала прогоняют nuqs-codemod-runner.
Какие задачи решает
- добавить фильтры и пагинацию на новую страницу Next.js
- перевести самодельные
useState-фильтры на nuqs - свести парсеры клиента и сервера к одной карте
- получить Zod-схему для query-параметров под tRPC
- сгенерировать тест на значения по умолчанию
Примеры запросов агенту
- Добавь фильтры на страницу
/search: поиск, страница, лимит и сортировка. - Сделай типизированную строку запроса для этой страницы через nuqs.
- Заполни
spec.jsonдля страницы и отрендери файлы по шаблонам.
Как установить nuqs-scaffolder
1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a claude-code2Вручную: положить файлы
~/.claude/skills/nuqs-scaffolder/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/nuqs-scaffolder/
1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a codex2Вручную: положить файлы
.agents/skills/nuqs-scaffolder/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a cursor2Вручную: положить файлы
.cursor/skills/nuqs-scaffolder/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/nuqs-scaffolder2Вручную: положить файлы
.github/skills/nuqs-scaffolder/SKILL.md1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a gemini-cli2Командой платформы
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/nuqs-scaffolderВручную: положить файлы
.devin/skills/nuqs-scaffolder/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о nuqs-scaffolder
Как установить nuqs-scaffolder в Claude Code?
Выполните npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a claude-code. Скилл окажется в ~/.claude/skills/nuqs-scaffolder/SKILL.md.
Что делает nuqs-scaffolder?
По одной JSON-спеке генерирует карту парсеров nuqs, серверный загрузчик со схемой, компонент фильтров и тест. Все файлы используют общие определения парсеров.
Что нужно для работы скилла?
Проект на Next.js с установленным nuqs. Типу array-of-string-native нужен nuqs 2.7 или новее, а тесты выпускаются, только когда в config.json стоит generate_tests: true, и рассчитаны на Vitest.
Исходный текст
SKILL.md · MIT
---
name: nuqs-scaffolder
description: Scaffolds URL-state filters for a Next.js page — typed `searchParams.ts` parser map and a `<Filters />` client component backed by `useQueryStates`. From a single JSON spec, generates four files in lockstep — client parser map, server loader/cache/serializer, client component, and Vitest test — all sharing the same parser definitions per the nuqs Standard Schema pattern. Trigger even when the user only says "add filters to /search" or "I need a typed query string for this page" — both are exactly this skill's job.
---
# nuqs Scaffolder
Generate a coherent set of nuqs files from one spec. The skill is **template-driven** — you read the spec, copy the templates, and substitute placeholders. No build step, no codegen runtime; the templates ARE the artifact.
## When to Apply
Use this skill when:
- A new Next.js page needs URL-backed filters, pagination, search, or sort state
- You're standardising an existing page's ad-hoc `useState` filters onto nuqs
- A code review keeps catching client/server drift in parser definitions — this skill makes drift mechanically impossible because both sides import the same map
- A user asks to "add Standard Schema validation to these query params for tRPC" — the generated `searchParams.server.ts` already exports the schema
If the codebase has legacy nuqs patterns instead, run the [`nuqs-codemod-runner`](../nuqs-codemod-runner/) skill first.
## How to Use
1. **Read or create a spec.** Start from `assets/templates/spec.template.json` and fill in `name`, `module`, and `params`. See "Spec Format" below.
2. **Render each template** by replacing placeholders with values derived from the spec.
3. **Write each rendered file** to the path computed from `config.json` (overridable per-call).
4. **Show the user the diff before committing** — this skill never modifies existing files; if a target path exists, ask before overwriting.
The agent does the rendering — Claude is the templating engine. Each template is annotated with markers (`/*= ... =*/`) that name the placeholder slot and document the substitution rule.
## Spec Format
```jsonc
{
"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 }
}
}
```
### Supported `type` values
| `type` | Parser used | Notes |
|--------|-------------|-------|
| `string` | `parseAsString` | |
| `integer` | `parseAsInteger` | |
| `float` | `parseAsFloat` | |
| `boolean` | `parseAsBoolean` | |
| `iso-date` | `parseAsIsoDate` | Date-only |
| `iso-date-time` | `parseAsIsoDateTime` | Date + time |
| `timestamp` | `parseAsTimestamp` | ms since epoch |
| `hex` | `parseAsHex` | Numeric value, hex URL form |
| `index` | `parseAsIndex` | 0-based in code, 1-based in URL |
| `array-of-string` | `parseAsArrayOf(parseAsString)` | `?tags=a,b,c` |
| `array-of-string-native` | `parseAsNativeArrayOf(parseAsString)` | `?tag=a&tag=b` — requires nuqs ≥ 2.7 |
| `string-literal` | `parseAsStringLiteral(values)` | Requires `values: string[]` |
| `number-literal` | `parseAsNumberLiteral(values)` | Requires `values: number[]` |
| `json` | `parseAsJson(SchemaName.parse)` | Generates a Zod schema stub; mark `default` separately |
If `default` is `null`, the param is nullable; otherwise the template uses `.withDefault(...)`.
## Available Templates
| Template | Renders to (default) | Loaded when |
|----------|----------------------|-------------|
| [`searchParams.ts.template`](assets/templates/searchParams.ts.template) | `lib/{module}-search-params.ts` | Always |
| [`searchParams.server.ts.template`](assets/templates/searchParams.server.ts.template) | `lib/{module}-search-params.server.ts` | Always |
| [`filters.tsx.template`](assets/templates/filters.tsx.template) | `components/{module}/{name}-filters.tsx` | Always |
| [`filters.test.tsx.template`](assets/templates/filters.test.tsx.template) | `components/{module}/{name}-filters.test.tsx` | If `config.generate_tests` is true |
| [`spec.json.template`](assets/templates/spec.json.template) | Anywhere — starter for the user | First-run prompt |
Template files end in `.template` so editors don't apply syntax highlighting to placeholder markers — the original extension is preserved as the suffix-before-`.template` so you can still tell at a glance what the rendered file will be.
Paths are configurable in `config.json` — override globs, file naming style (kebab vs PascalCase), and whether tests are emitted.
## Placeholder Reference
All templates use the same placeholder syntax. The agent substitutes them in one pass:
| Placeholder | Source | Example |
|-------------|--------|---------|
| `__NAME__` | `spec.name` | `Search` |
| `__name__` | camelCase form of `spec.name` | `search` |
| `__module__` | `spec.module` | `search` |
| `/*= PARSERS =*/` | Iterate `spec.params` → `key: parseAsXxx.withDefault(...)` lines | see template |
| `/*= COMPONENT_FIELDS =*/` | Iterate `spec.params` → one input/select per type | see template |
| `/*= TEST_CASES =*/` | Iterate `spec.params` → one assertion per default | see template |
| `/*= NULLABLE_IMPORTS =*/` | Add `Nullable` helper import if any param is nullable | conditional |
| `/*= ZOD_SCHEMAS =*/` | For `json` type params, emit a Zod schema stub | conditional |
`/*= ... =*/` markers are **instructions to the agent**, not literal substitutions. Replace the entire marker (including the `/*= =*/` delimiters) with the expanded content.
## Conventions
Read [`references/conventions.md`](references/conventions.md) for:
- File naming (kebab-case) and why
- Import ordering (external → nuqs → internal → relative) and why
- Why the server file exists as a sibling, not inside `app/`
- When to fork the templates (you usually shouldn't)
## Setup
`config.json` is pre-populated with sensible Next.js App Router defaults. Override only if your repo uses different conventions:
```jsonc
{
"lib_dir": "lib",
"components_dir": "components",
"generate_tests": true,
"test_runner": "vitest"
}
```
On first use, the agent should ask the user for the spec via `AskUserQuestion` if no spec file is provided.
## Related Skills
- [`nuqs`](../nuqs/) — Best-practice reference these templates encode. Read it to understand WHY the templates are shaped this way.
- [`nuqs-codemod-runner`](../nuqs-codemod-runner/) — Run BEFORE this skill if migrating an existing page from pre-v2.5 nuqs.
## Gotchas
See [`gotchas.md`](gotchas.md) for edge cases discovered during use.
© pproenca · MIT · pproenca/dot-skills