react-hook-form-audit
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. 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.
- License 许可
- MIT
- 最近更新
- 2026-08-02
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- 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. 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.
02 资源文件 12
- 参考文档config.json1.4 KB
- 参考文档gotchas.md233 B
- 参考文档references/detectors.md10.9 KB
- 参考文档references/workflow.md8.5 KB
- 脚本scripts/.gitignore32 B
- 脚本scripts/audit.sh5.1 KB
- 脚本scripts/collect-files.sh1.3 KB
- 脚本scripts/detect-ast.mjs18.9 KB
- 脚本scripts/detect-fast.sh3.2 KB
- 脚本scripts/detect-project.sh1.9 KB
- 脚本scripts/package.json281 B
- 脚本scripts/render-report.mjs4.3 KB
03 SKILL.md 正文
React Hook Form Audit for Next.js
Static-analysis audit that detects 15 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 viabrew install ripgrepor your package managernode≥ 18 withnpm— used to run the AST detectors viats-morphjq— 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-4, 6-10, 12-13, 15)
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 findings1— CRITICAL or HIGH findings exist2— environment or configuration error (missing tool, invalid project)
Detector Catalog
15 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 |
| 04 | CRITICAL | useEffect depends on the useForm return |
| 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) |
How to Use
- Confirm project is a Next.js App Router app with react-hook-form installed (
detect-project.shwill check) - Run
bash scripts/audit.sh [--project <path>] - Read the generated
.rhf-audit-report.mdin 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 linksinclude_globs/exclude_globs— narrow the scan surface
Reference Files
references/workflow.md— detailed workflow, error handling, CI integrationreferences/detectors.md— per-detector spec, AST shape, false-positive notesgotchas.md— accumulated failure modes (append-only)
Related Skills
react-hook-form— the companion distillation skill with the 45 rules this auditor enforces. Findings link directly to its reference files.react-19— for Server Action /useActionStatepatterns the audit explicitly does NOT cover
04 同仓库更多 Skills
zustand
Rules and standards for state management using Zustand in React and Next.js. Use when implementing client-side stores, persistence with localStorage, or preventing SSR hydration mismatch.
zod
Zod v4 schema validation best practices. Use when defining schemas, utilizing safeParse, or customizing error messages.
upstash-ratelimit
Rules, standards, and references for rate limiting in serverless environments using Upstash Ratelimit. Use when implementing rate limiting, configuring Upstash Redis, or handling request blocking.
ui-design
UI/UX and frontend design best practices guidelines (formerly frontend-design). This skill should be used when writing, reviewing, or designing frontend code to ensure accessibility, performance, and usability. Triggers on tasks involving HTML structure, CSS styling, responsive layouts, form design, animations, or accessibility improvements.
typescript
TypeScript performance, tsconfig, type errors, async patterns — triggered when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
typescript-refactor
TypeScript and TSX refactoring and modernization guidelines from a principal specialist perspective, current to TypeScript 6.0 and React 19. This skill should be used when refactoring, reviewing, or modernizing TypeScript or React/TSX code for type safety, compiler performance, and idiomatic patterns. Triggers on tasks involving type architecture, narrowing, generics, discriminated unions, error handling, React component and hook typing, or migration to modern TypeScript features (satisfies, using, const type parameters, inferred type predicates, isolatedDeclarations, erasable syntax, import attributes).