Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-code
Open on GitHub

What 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 throttleMs calls with the modern limitUrlUpdates: throttle(N) pattern
  • Eliminate boilerplate useState and useEffect debounce routines in favor of nuqs native helpers
  • Inject Zod schemas or type-guard stubs into unchecked parseAsJson definitions
  • Upgrade unversioned React Router adapter imports to the explicit v6 path
  • Migrate deprecated ParserBuilder<T> declarations to SingleParserBuilder<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-code

2Manually: put the files in place

~/.claude/skills/nuqs-codemod-runner/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nuqs-codemod-runner/

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

Similar skills

All skills for Code review and refactoring →

From the same set139

The whole set →
implementation-design-patterns-python implementation-design-patterns-python — a Python design-pattern guide for choosing an approach when conditionals, inheritance, or object relationships start to sprawl. It favors modern Python idioms over class-heavy templates. CX Codex +1 143installs better-auth-scaffold better-auth-scaffold scaffolds Better Auth in a Next.js App Router project on Drizzle: file templates, three plugin presets, schema generation and migrations. CX Codex +1 143installs expo-ui Guidance for building and reviewing React Native screens with @expo/ui on iOS. Useful when adopting SwiftUI views or working with iOS 26 interface features. CX Codex +1 142installs design-to-react-algorithms The design-to-react-algorithms skill provides a step-by-step pipeline to convert Sketch files into React and CSS while preventing layout regressions. CX Codex +1 142installs acceptance-pipeline-catalog acceptance-pipeline-catalog guides code agents through building, reviewing, and debugging Gherkin acceptance test pipelines with mutation testing based on Robert C. Martin's specification. CX Codex +1 142installs inngest-nextjs-patterns inngest-nextjs-patterns — a template pack for Inngest background work in a Next.js App Router project: the client, the /api/inngest handler, typed events, cron jobs and fan-out functions. CX Codex +1 141installs acceptance-pipeline-feature-design The acceptance-pipeline-feature-design skill helps design Acceptance Pipeline extensions, covering Gherkin syntax, JSON IR fields, pipeline stages, mutation strategies, and reports. CX Codex +1 141installs dx-harness dx-harness — a skill for Claude Code, Cursor, and other IDEs that finds and fixes developer-loop friction — slow onboarding, repeated manual steps, missing bootstrap and reset scripts. CX Codex +1 141installs

Project sponsors

Companies that keep this analytics open