К основному содержанию
скилл CX Codex

nuqs-scaffolder — скилл для Claude Code: URL-фильтры в Next.js

Скилл nuqs-scaffolder собирает из одного JSON-описания четыре файла для фильтров в URL на Next.js: карту парсеров, серверный загрузчик, клиентский компонент и тест.

MIT 145 установок ★ 227 обновлён 2026-08-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/nuqs-scaffolder/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/nuqs-scaffolder/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
url-state-patterns andrelandgraf Скилл url-state-patterns для Claude Code связывает состояние React с параметрами URL через nuqs. Он подключается при создании фильтров, поиска и диалогов, которыми можно делиться ссылкой. CX Codex +1 110установок saas-scaffolder Alireza Rezvani Скилл saas-scaffolder для Claude Code, который генерирует рабочий каркас SaaS на Next.js: авторизация, схема базы, биллинг Stripe, API-роуты и дашборд. CX Codex +1 630установок project-scaffolder patricio0312rev Скилл project-scaffolder разворачивает стартовые репозитории под популярные фреймворки с настроенным линтингом, тестовым эндпоинтом и документацией по запуску. CX Codex +1 287установок api-endpoint-scaffolder OneWave-AI Скилл api-endpoint-scaffolder собирает REST-эндпоинты по шаблонам для Next.js App Router и Express: схема Zod, коды ответов, обработка ошибок. CX Codex +1 317установок embedded-agents-agent-sdk Paweł Huryn Скилл embedded-agents-agent-sdk для Claude Code и Codex встраивает агентов Claude в приложение на Next.js через Claude Agent SDK. Запускается при запросе на интеграцию Agent SDK или когда агенту нужен движок Claude Code. CX Codex +1 ★ 741звёзд репо safe-action-testing next-safe-action Скилл safe-action-testing подсказывает агенту, как писать тесты для экшенов и хуков next-safe-action на Vitest: валидация, middleware, серверные ошибки. CX Codex +1 1 200установок

Из того же набора139

Весь набор →
same-results-less-code Скилл same-results-less-code помогает находить лишнюю сложность при ревью и рефакторинге, сохраняя поведение кода. Он дополняет линтеры анализом структуры и моделей. CX Codex +1 148установок codebase-comprehension-algorithms Скилл codebase-comprehension-algorithms раскладывает незнакомый репозиторий на функциональные домены: какие файлы стоят за фичей и где проходит архитектурный каркас. CX Codex +1 148установок storybook Помогает настраивать Storybook и писать истории для TypeScript/React-компонентов. Описывает интерактивные тесты, проверку доступности и сборку документации. CX Codex +1 145установок code-map-visualization Скилл code-map-visualization учит агента рисовать карту кодовой базы: какие данные класть на цвет и размер, как уложиться в 16 мс на кадр и не потерять читаемость. CX Codex +1 145установок migrate-js-to-modern-typescript Скилл migrate-js-to-modern-typescript пошагово переводит проект с JavaScript на строгий TypeScript, настраивает tsconfig и помогает отказаться от any без поломки сборки. CX Codex +1 145установок radical-simplification Скилл radical-simplification для Claude Code разбирает сложные инженерные и продуктовые задачи через смену рамки, упрощение и проверку предположений. Помогает выйти из тупика. CX Codex +1 144установок base-ui-migrator Скилл base-ui-migrator переводит React-компоненты с Radix UI, Headless UI или самописных оверлеев на Base UI (@base-ui/react). Помогает стандартизировать интерфейс без потери стилей. CX Codex +1 144установок implementation-design-patterns-python Скилл implementation-design-patterns-python для Claude Code помогает выбирать и применять паттерны проектирования в современном Python. Он помогает разбираться с разрастающимися ветвлениями, наследованием и связями между объектами. CX Codex +1 143установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой