react-hook-form-audit — Claude Code skill: RHF anti-pattern audit
react-hook-form-audit scans a Next.js App Router project for 16 React Hook Form anti-patterns and writes a markdown report citing file:line. Read-only.
MIT 158 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill react-hook-form-audit -a claude-codeWhat react-hook-form-audit does
A static pass over your forms code. Regex rules run through rg, structural ones go through ts-morph and the AST. The catalog holds 16 detectors in four severity tiers, from watch() sitting next to useForm() to useFieldArray({ disabled }) quietly swallowing mutations, plus useEffect with reset(data) where the values prop belongs. Each detector spec, false-positive notes included, lives in references/detectors.md.
Run bash scripts/audit.sh. Add --project /path/to/nextjs-app to point it elsewhere, or --dry-run to skip writing the file. Findings land in .rhf-audit-report.md at the project root, grouped by severity, every one tied to a line and linked to the matching rule in the companion react-hook-form skill. Exit code 1 means CRITICAL or HIGH findings, which is how the run becomes a CI gate.
rg, jq and node ≥ 18 with npm have to be on the machine; miss one and the script exits with code 2 without a report. ts-morph goes into scripts/node_modules/ on the first run, so the audited project's own node_modules stays untouched. Narrow noisy detectors through include_globs and exclude_globs in config.json instead of switching them off.
What it helps with
- catch forms that re-render on every keystroke
- check new RHF code before a PR review
- flag RHF imports in files missing
"use client" - fail CI when a form breaks a CRITICAL rule
- explain why a
useFieldArraylist never updates
Example prompts for the agent
- Audit the React Hook Form usage in this Next.js app and list only CRITICAL findings.
- Run a form anti-pattern check on the project and leave the report in the root.
- Do a dry run of the forms audit, I want the findings without a report file.
How to install react-hook-form-audit
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill react-hook-form-audit -a claude-code2Manually: put the files in place
~/.claude/skills/react-hook-form-audit/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/react-hook-form-audit/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill react-hook-form-audit -a codex2Manually: put the files in place
.agents/skills/react-hook-form-audit/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill react-hook-form-audit -a cursor2Manually: put the files in place
.cursor/skills/react-hook-form-audit/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/react-hook-form-audit2Manually: put the files in place
.github/skills/react-hook-form-audit/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill react-hook-form-audit -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/react-hook-form-auditManually: put the files in place
.devin/skills/react-hook-form-audit/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill react-hook-form-audit -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 react-hook-form-audit
How do I install react-hook-form-audit in Claude Code?
Run npx skills add pproenca/dot-skills --skill react-hook-form-audit -a claude-code; the skill file then sits at ~/.claude/skills/react-hook-form-audit/SKILL.md.
What does react-hook-form-audit do?
It reviews a Next.js App Router codebase for React Hook Form anti-patterns and produces a markdown report with line references that point back to rules in the react-hook-form skill.
Which tools does it need?
rg, node ≥ 18 with npm, and jq. On the first run the skill installs ts-morph into scripts/node_modules/ on its own.
Source text
SKILL.md · MIT
---
name: react-hook-form-audit
description: Audits a Next.js (App Router, 14/15+) codebase for React Hook Form anti-patterns — watch() at form root, Controller inlined in parent, async submit without try/catch, missing setError on server failures, RHF in non-"use client" files, RHF mixed with useActionState, schemas defined inside components, useFieldArray without field.id keys, register({ disabled }) for visual disabling, useFieldArray({ disabled }) that silently no-ops mutations, useEffect+reset(data) instead of the values prop. Read-only; emits a markdown report with file:line citations linking back to the companion `react-hook-form` distillation skill. Trigger when the user asks to audit/review/lint RHF usage, find form anti-patterns, or run a quality check on forms — even if they don't say "react-hook-form" by name; if they mention auditing forms in a Next.js project, use this skill.
---
# React Hook Form Audit for Next.js
Static-analysis audit that detects 16 React Hook Form anti-patterns in Next.js App Router codebases. Combines ripgrep (fast pass for regex-detectable rules) with ts-morph (AST pass for structural rules). Outputs a markdown report grouped by severity, with file:line references and links back to the companion `react-hook-form` distillation skill.
## When to Apply
- User asks to audit, review, or lint React Hook Form usage in a Next.js project
- User reports symptoms like "the form re-renders too much" or "we have RHF bugs we can't pin down"
- Before a PR review of new RHF-heavy code
- As a CI gate (exit code 1 on CRITICAL/HIGH findings)
- After upgrading react-hook-form, to catch advice that drifted
## Tool Requirements
- `rg` (ripgrep) — install via `brew install ripgrep` or your package manager
- `node` ≥ 18 with `npm` — used to run the AST detectors via `ts-morph`
- `jq` — for JSON munging in the orchestrator
`ts-morph` is installed on first run into `scripts/node_modules/` (one-time, ~30s). The skill never touches the audited project's `node_modules`.
## Risk Level
**Read-only.** The skill reads source files and writes one markdown report (plus an optional JSON sidecar) to the audited project root. No git operations, no package mutations, no network calls.
## Workflow Overview
```
1. detect-project.sh Verify Next.js + react-hook-form in package.json
2. collect-files.sh Ripgrep for "use client" files importing RHF
3. detect-fast.sh Ripgrep detectors (rules 5, 11, 14)
4. detect-ast.mjs ts-morph detectors (rules 1-3, 6-10, 12-13, 15-17)
5. render-report.mjs Render markdown + JSON; print summary; exit 0/1
```
See [`references/workflow.md`](references/workflow.md) for the per-step contract, error handling, and CI integration.
## Usage
```bash
# Audit the current directory
bash scripts/audit.sh
# Audit a specific project
bash scripts/audit.sh --project /path/to/nextjs-app
# Preview without writing the report file
bash scripts/audit.sh --dry-run
```
Exit codes:
- `0` — no CRITICAL or HIGH findings
- `1` — CRITICAL or HIGH findings exist
- `2` — environment or configuration error (missing tool, invalid project)
## Detector Catalog
16 detectors across 4 severities. See [`references/detectors.md`](references/detectors.md) for per-rule pattern, AST shape, false-positive notes, and the line of advice each detector enforces.
| ID | Severity | What it catches |
|----|---------|-----------------|
| 01 | CRITICAL | `watch()` in same component as `useForm()` |
| 02 | CRITICAL | `watch()` with no args (subscribes to all fields) |
| 03 | CRITICAL | `useForm()` without `defaultValues` |
| 05 | CRITICAL | RHF imported in a non-`"use client"` file |
| 06 | HIGH | `<Controller>` inlined inside `useForm()` parent |
| 07 | HIGH | Async submit handler without `try/catch` |
| 08 | HIGH | Validation schema defined inside the component |
| 09 | HIGH | Submit calls fetch/axios but never `setError('root.*')` |
| 10 | HIGH | RHF mixed with `useActionState` in same component |
| 11 | MEDIUM | `mode: 'onChange'` without explanatory comment |
| 12 | MEDIUM | `register({ disabled: <state> })` for visual disable |
| 13 | MEDIUM | `useFieldArray` map missing `field.id` as key |
| 14 | LOW | `reValidateMode: 'onBlur'` (now demoted advice) |
| 15 | LOW | `useFormContext()` usage (manual review) |
| 16 | MEDIUM | `useFieldArray({ disabled: <state> })` — silently no-ops every mutation |
| 17 | MEDIUM | `useEffect` + `reset(data)` instead of the `values` prop |
Rule 04 (`useEffect` depends on the `useForm` return) was **removed** in 0.2.0 — the premise was false. See [`references/detectors.md`](references/detectors.md).
## How to Use
1. Confirm project is a Next.js App Router app with react-hook-form installed (`detect-project.sh` will check)
2. Run `bash scripts/audit.sh [--project <path>]`
3. Read the generated `.rhf-audit-report.md` in the project root
4. For each finding, follow the link to the companion distillation rule for the fix
5. After fixing, re-run to verify a clean audit
If a detector is too noisy in your project, narrow `include_globs` / widen `exclude_globs` in `config.json` rather than disabling detectors — the catalog is small enough that each finding should be either a real issue or a documented exception worth a comment.
## Setup
The skill ships with sensible defaults in `config.json`. On first run, `audit.sh` will install `ts-morph` into `scripts/node_modules/`. Override settings by editing `config.json`:
- `project_root` — absolute path to the project (defaults to current directory)
- `report_path` / `json_report_path` — output filenames (relative to project root)
- `rule_link_base` — base URL or path for companion-rule links
- `include_globs` / `exclude_globs` — narrow the scan surface
## Reference Files
- [`references/workflow.md`](references/workflow.md) — detailed workflow, error handling, CI integration
- [`references/detectors.md`](references/detectors.md) — per-detector spec, AST shape, false-positive notes
- [`gotchas.md`](gotchas.md) — accumulated failure modes (append-only)
## Related Skills
- `react-hook-form` — the companion distillation skill with the 35 rules this auditor enforces. Findings link directly to its reference files.
- `react-19` — for Server Action / `useActionState` patterns the audit explicitly does NOT cover
© pproenca · MIT · pproenca/dot-skills