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 for the per-step contract, error handling, and CI integration.

Usage

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

How to Use

Confirm project is a Next.js App Router app with react-hook-form installed (detect-project.sh will check)
Run bash scripts/audit.sh [--project <path>]
Read the generated .rhf-audit-report.md in the project root
For each finding, follow the link to the companion distillation rule for the fix
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 — detailed workflow, error handling, CI integration
references/detectors.md — per-detector spec, AST shape, false-positive notes
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

react-hook-form-audit