nuqs-codemod-runner — Claude Code skill: setup and usage
nuqs-codemod-runner finds pre-v2.5 nuqs patterns, produces a dry-run migration preview, and applies safe jscodeshift transforms gated by type checking and linting.
MIT 142 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-codeWhat nuqs-codemod-runner does
The skill manages transitions from legacy nuqs setups to v2.5–v2.8 conventions. Its initial step runs scripts/scan.sh across .ts, .tsx, .js, and .jsx files. It catches five legacy targets: deprecated throttleMs, manual useState and setTimeout debounce wrappers around useQueryState, unvalidated parseAsJson casts, unversioned React Router adapter imports, and outdated ParserBuilder<T> type annotations.
Before modifying code, the runner prints a detailed markdown diff table and waits for explicit approval. Transformations run via jscodeshift scripts. Once finished, scripts/verify.sh executes tsc --noEmit alongside the project lint script, triggering an automatic git restore if any check fails.
Execution halts immediately if your git working tree has uncommitted modifications, requiring a clean working state or explicit override flags.
What it helps with
- Replace legacy
throttleMscalls with the modernlimitUrlUpdates: throttle(N)pattern - Eliminate boilerplate
useStateanduseEffectdebounce routines in favor of nuqs native helpers - Inject Zod schemas or type-guard stubs into unchecked
parseAsJsondefinitions - Upgrade unversioned React Router adapter imports to the explicit v6 path
- Migrate deprecated
ParserBuilder<T>declarations toSingleParserBuilder<T>
Example prompts for the agent
- Upgrade our codebase to nuqs v2.5 and display a dry-run report before applying changes
- Scan this repository for deprecated nuqs patterns and run the codemods
- Replace manual setTimeout debounce around useQueryState with limitUrlUpdates
How to install nuqs-codemod-runner
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-code2Manually: put the files in place
~/.claude/skills/nuqs-codemod-runner/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nuqs-codemod-runner/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a codex2Manually: put the files in place
.agents/skills/nuqs-codemod-runner/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a cursor2Manually: put the files in place
.cursor/skills/nuqs-codemod-runner/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/nuqs-codemod-runner2Manually: put the files in place
.github/skills/nuqs-codemod-runner/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/nuqs-codemod-runnerManually: put the files in place
.devin/skills/nuqs-codemod-runner/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -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-codemod-runner
How to install nuqs-codemod-runner in Claude Code?
Run npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-code. The tool downloads the skill to ~/.claude/skills/nuqs-codemod-runner/SKILL.md.
What does nuqs-codemod-runner do?
It scans repositories for legacy pre-v2.5 nuqs patterns, formats a dry-run confirmation table, applies AST refactorings, and validates the codebase using TypeScript and linter checks.
How does the skill prevent breaking changes in production code?
The workflow runs in read-only mode until confirmed, refuses dirty git worktrees, and reverts all touched files with git restore if tsc --noEmit or the linter reports errors.
Source text
SKILL.md · MIT
---
name: nuqs-codemod-runner
description: Migrates a nuqs codebase off pre-v2.5 patterns — deprecated `throttleMs`, hand-rolled setTimeout/useState debounce around `useQueryState`, unchecked `parseAsJson` casts, unversioned `nuqs/adapters/react-router` imports, or `ParserBuilder<T>` type references. Scans the repo, produces a dry-run report, asks for confirmation, applies AST codemods, then runs `tsc --noEmit` + the user's lint as a gate. Trigger even if the user only mentions "upgrade nuqs" or "migrate to nuqs v2.5+" without naming the specific patterns — they almost always exist in pre-v2.5 codebases.
---
# nuqs Codemod Runner
Migrate a codebase from pre-v2.5 nuqs patterns to current v2.5–v2.8 idioms. The skill is **read-only by default** — it never modifies files without an explicit confirmation step, and refuses to run on a dirty git working tree.
## When to Apply
Trigger this skill when:
- A user asks to "upgrade nuqs" or "migrate to nuqs 2.x" in a project that already uses nuqs
- You spot any of the 5 legacy patterns during a review (see the codemod table below)
- A `nuqs` version bump in `package.json` from `<2.5` to `>=2.5` is part of the diff
- The user has just installed/updated the [`nuqs` skill](../nuqs/SKILL.md) and wants to bring existing code into line with it
This skill is the **automation companion** to `skills/.curated/nuqs/` — that skill teaches what each correct pattern looks like; this skill rewrites legacy code to match.
## Workflow Overview
```
┌──────────┐ ┌────────────┐ ┌──────────────────┐ ┌───────────┐ ┌────────────┐
│ scan.sh │──▶ │ scan.json │──▶ │ report.sh │──▶ │ apply.sh │──▶ │ verify.sh │
└──────────┘ └────────────┘ │ (dry-run table) │ │ (codemods)│ │ (tsc+lint) │
└──────────────────┘ └───────────┘ └────────────┘
│ ▲ │
▼ │ ▼
user reviews ──────────── confirms on fail: revert
```
1. **`scripts/scan.sh <repo-root>`** — ripgreps every `.ts/.tsx/.js/.jsx` file for the 5 legacy patterns, emits `scan.json` with `{path, line, matchedPattern, snippet, suggestion}`.
2. **`scripts/report.sh`** — renders `scan.json` as a markdown table grouped by codemod, with file paths and before/after pairs. **Show this output to the user verbatim** and ask for explicit confirmation before continuing.
3. **`scripts/apply.sh [--filter <codemod-id>]`** — runs the jscodeshift transforms in `scripts/transforms/`. Refuses to run unless a fresh `scan.json` exists for the current `git HEAD` and the working tree is clean (`--allow-dirty` overrides).
4. **`scripts/verify.sh`** — runs `tsc --noEmit` and `npm run lint` (or the equivalent commands from `config.json`). If anything fails, `git restore` reverts every file the codemod touched.
Run all four sequentially. If the user only wants to scan, stop at step 2.
## The Five Codemods
| ID | Detects | Rewrites to |
|----|---------|-------------|
| `throttle-ms` | `withOptions({ throttleMs: N })` or `setX(v, { throttleMs: N })` | `withOptions({ limitUrlUpdates: throttle(N) })` + adds `throttle` to the `nuqs` import |
| `manual-debounce` | `useState` mirror + `useEffect` + `setTimeout` debounce around a `useQueryState` setter | `withOptions({ limitUrlUpdates: debounce(N) })` + adds `debounce` to the `nuqs` import; deletes the mirror state and effect |
| `unchecked-json-cast` | `parseAsJson<T>()` (no validator) or `parseAsJson((v) => v as T)` | Inserts a `// TODO: validate` type-guard stub or, if Zod is detected in `package.json`, a `parseAsJson(SchemaName.parse)` form |
| `react-router-unversioned` | `from 'nuqs/adapters/react-router'` | `from 'nuqs/adapters/react-router/v6'` (the alias the unversioned import historically pointed at) |
| `parser-builder-type` | type references to `ParserBuilder<T>` from `nuqs` | `SingleParserBuilder<T>` |
See [`references/workflow.md`](references/workflow.md) for the exact AST shapes each codemod matches and the edge cases it deliberately skips.
## Setup
On first run, `config.json` is populated with the user's lint/typecheck commands and a default `min_node_version`. See `_setup_instructions` in `config.json` for what to fill in.
## Risk & Guardrails
This skill is **write-risk** (it modifies source files). Guardrails:
- `apply.sh` aborts if the working tree is dirty (use `git stash` first, or pass `--allow-dirty` after reading [`gotchas.md`](gotchas.md))
- `apply.sh` aborts if `scan.json` is older than 60 minutes or was generated against a different `git HEAD` — re-run `scan.sh`
- The `hooks/hooks.json` PreToolUse matcher blocks any direct `node scripts/transforms/*.js` invocation that bypasses the orchestrator
- `verify.sh` auto-reverts on TS or lint failure via `git restore` over the touched files (recorded in `last-run.json`)
## Related Skills
- [`nuqs`](../nuqs/) — Best-practice reference for nuqs v2.5+. This skill rewrites legacy code; that skill defines the target.
## Gotchas
See [`gotchas.md`](gotchas.md) for failure modes discovered during use.
© pproenca · MIT · pproenca/dot-skills