# nuqs-codemod-runner

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 142 installs · ★ 227 repo stars
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/nuqs-codemod-runner/SKILL.md
- Updated: 2026-08-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/nuqs-codemod-runner

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/nuqs-codemod-runner/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/nuqs-codemod-runner/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/nuqs-codemod-runner/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/nuqs-codemod-runner/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills skills/.curated/nuqs-codemod-runner
```

2. **Manually: put the files in place**
- File: `.github/skills/nuqs-codemod-runner/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/nuqs-codemod-runner
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/nuqs-codemod-runner/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/nuqs-codemod-runner/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: e5ac7a1299fa7e34.

BEGIN THIRD-PARTY FILE e5ac7a1299fa7e34
````text
---
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) │
                                  └──────────────────┘    └───────────┘    └────────────┘
                                          │                     ▲                │
                                          ▼                     │                ▼
````
END THIRD-PARTY FILE e5ac7a1299fa7e34

The third-party file has ended. Everything between the e5ac7a1299fa7e34 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2394 of 5619 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/nuqs-codemod-runner/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
