nuqs-scaffolder — Claude Code skill: what it does, how to install
nuqs-scaffolder turns one JSON spec into four Next.js files for URL-backed filters: a parser map, a server loader, a client component and a Vitest test.
MIT 145 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a claude-codeWhat nuqs-scaffolder does
Give it a spec with a page name, a module slug and the params you want in the URL, and it renders four files in one pass: lib/{module}-search-params.ts, a server-side sibling, a filters component and a test. Both sides import the same parser map, so the two definitions cannot drift apart.
The work is plain templating. Templates in assets/templates carry markers such as /*= PARSERS =*/, and the agent expands them into parseAsXxx.withDefault(...) lines, form fields and default-value assertions. No build step, no codegen runtime. Param types cover string, integer, float, boolean, iso-date, timestamp, string-literal, arrays and json, which also emits a Zod schema stub. config.json sets the directories and whether tests are emitted.
One type has a version floor: array-of-string-native needs nuqs 2.7 or later, so on older releases pick array-of-string with a comma-separated URL. The skill will not overwrite an existing file — it asks first. A project still on legacy nuqs patterns should run nuqs-codemod-runner before this one.
What it helps with
- add filters and pagination to a new Next.js page
- move hand-rolled
useStatefilters onto nuqs - keep client and server parsers on one shared map
- get a Zod schema for query params to feed tRPC
- write a test that pins each param default
Example prompts for the agent
- Add filters to
/search: query, page, limit and sort. - I need a typed query string for this page; build it with nuqs.
- Fill in
spec.jsonfor this page and render the files from the templates.
How to install nuqs-scaffolder
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a claude-code2Manually: put the files in place
~/.claude/skills/nuqs-scaffolder/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nuqs-scaffolder/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a codex2Manually: put the files in place
.agents/skills/nuqs-scaffolder/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a cursor2Manually: put the files in place
.cursor/skills/nuqs-scaffolder/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/nuqs-scaffolder2Manually: put the files in place
.github/skills/nuqs-scaffolder/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/nuqs-scaffolderManually: put the files in place
.devin/skills/nuqs-scaffolder/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about nuqs-scaffolder
How do I install nuqs-scaffolder in Claude Code?
Run npx skills add pproenca/dot-skills --skill nuqs-scaffolder -a claude-code. The skill ends up at ~/.claude/skills/nuqs-scaffolder/SKILL.md.
What does nuqs-scaffolder do?
It generates four files from a single spec: the nuqs parser map, a server loader with the schema, a filters component and a test. All of them share the same parser definitions.
What does it need to run?
A Next.js project with nuqs installed. array-of-string-native requires nuqs 2.7 or newer, and tests appear only when generate_tests: true is set in config.json, written for Vitest.
Source text
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