by datagrove-nl
Claude skill: audit a Next.js App Router codebase for RSC boundary bugs, request waterfalls, and Core Web Vitals risks — with a zero-dependency scanner.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
# Add to your Claude Code skills
git clone https://github.com/datagrove-nl/nextjs-app-router-auditGuides for using ai agents skills like nextjs-app-router-audit.
No comments yet. Be the first to share your thoughts!
Unlocks once the catalog security scan passes (runs nightly).
Find the high-impact correctness and performance problems in a Next.js App Router codebase, ranked by severity, each with a specific fix. Combine the bundled scanner (fast, mechanical) with a targeted manual pass (judgment calls the scanner can't make).
The scanner is dependency-free and reads only source files. Point it at the
project root or an app/ directory:
node scripts/audit.mjs /path/to/project # human-readable report + score
node scripts/audit.mjs /path/to/project --json # machine-readable for CI / further processing
It finds the app/ (or src/app/) dir itself, walks all .tsx/.ts/.jsx/.js,
and reports ERROR / WARN / INFO findings with file:line, the reason, and
a fix. Exit code is non-zero when any ERROR exists, so it drops into CI.
What it detects:
| Rule | Severity | Why it matters |
|---|---|---|
client-route-no-metadata |
ERROR | A "use client" page/layout silently drops metadata — SEO tags never ship. |
legacy-next-head |
ERROR | next/head is a no-op in the App Router — its tags never reach <head>. |
legacy-next-image |
WARN | next/legacy/image keeps old layout-shift-prone behavior. |
needless-use-client |
WARN | "use client" with no hooks/handlers/browser APIs — pushes JS to the client for nothing. |
client-fetch-in-effect |
WARN | Fetching in useEffect adds a render round-trip; move it server-side. |
raw-img |
WARN | <img> skips next/image sizing/lazy-loading — CLS & LCP regressions. |
unoptimized-font |
WARN | Fonts via <link>/@import are render-blocking; use next/font. |
page-missing-metadata |
WARN | Async page exports no metadata/generateMetadata. |
dangerous-html |
WARN | dangerouslySetInnerHTML — XSS risk if unsanitized. |
request-waterfall |
INFO | ≥2 sequential awaited fetches, no Promise.all. |
no-streaming-fallback |
INFO | Async page with no loading.tsx/Suspense — no streamed shell. |
force-dynamic |
INFO | Route opts out of static/ISR rendering — confirm it's intentional. |
large-client-component |
INFO | Big Client Component ships entirely to the browser. |
The scanner is heuristic (regex-based, not a full type-check): treat findings as strong leads, confirm each against the source before reporting it as fixed.
Read reference/checklist.md and verify the items that need real understanding:
"use client" boundary as low
in the tree as possible? Is a server-only secret (API key, DB client) imported
into a client module?fetch/unstable_cache/revalidate match how
fresh the data must be? Over-caching ships stale data; under-caching kills TTFB.generateStaticParams / ISR — are dynamic routes pre-rendered where they can be?revalidatePath/
revalidateTag instead of client fetches to route handlers?Lead with the ERRORs, then WARN, then the highest-leverage INFOs. For each:
file:line, one line on the impact, and the concrete fix (often a small diff).
End with the score and the 3 changes with the best effort-to-impact ratio. Don't
dump every INFO — curate.
node_modules/next/dist/docs/ if an API is uncertain rather than assuming.Built and maintained by Datagrove — a Dutch web development agency specializing in fast, well-architected Next.js websites. Need an audit or a rebuild? Talk to Datagrove.
A Claude skill that audits a Next.js App Router codebase for the mistakes that actually cost you — React Server Component boundary errors, request waterfalls, client/server anti-patterns, and Core Web Vitals regressions — and proposes concrete fixes ranked by severity.
It ships a zero-dependency static scanner plus a manual-review methodology for the judgment calls static analysis can't make.
| Rule | Severity | Why it matters |
|---|---|---|
client-route-no-metadata |
ERROR | A "use client" page silently drops metadata — your SEO tags never ship. |
legacy-next-head |
ERROR | next/head is a no-op in the App Router — its tags never reach <head>. |
legacy-next-image |
WARN | next/legacy/image keeps old layout-shift-prone behavior. |
needless-use-client |
WARN | "use client" with no interactivity — JS shipped to the browser for nothing. |
client-fetch-in-effect |
WARN | Fetching in useEffect adds a render round-trip; move it server-side. |
raw-img |
WARN | <img> skips next/image — CLS & LCP regressions. |
unoptimized-font |
WARN | Network web fonts are render-blocking; use next/font. |
page-missing-metadata |
WARN | Async page ships with no title/description. |
dangerous-html |
WARN | dangerouslySetInnerHTML — XSS risk if unsanitized. |
request-waterfall |
INFO | Sequential awaited fetches that should be Promise.all. |
no-streaming-fallback |
INFO | Async page with no loading.tsx / Suspense. |
force-dynamic |
INFO | Route opts out of static/ISR rendering. |
large-client-component |
INFO | Big Client Component ships entirely to the browser. |
No install, no dependencies — just Node 18+:
node scripts/audit.mjs /path/to/your/nextjs-project
node scripts/audit.mjs /path/to/your/nextjs-project --json # CI-friendly, exits non-zero on errors
Next.js App Router audit — 41 files in app/
ERROR client-route-no-metadata app/dashboard/page.tsx:1
A Client Component page cannot export `metadata` — its SEO tags are silently dropped.
fix: Keep page.tsx a Server Component and isolate the interactive bits into a child marked "use client".
Summary 1 error 3 warn 9 info score 67/100
See examples/sample-report.md for full output
against the bundled fixture app.
Drop it into CI to fail a PR when a route loses its metadata or leaks a secret into the client bundle.
Place the folder in your skills directory (e.g. ~/.claude/skills/) or upload it
to your skills hub, then ask:
"Audit this Next.js app for performance and RSC problems."
Claude runs the scanner, does the manual checklist pass in reference/checklist.md,
and reports the highest-leverage fixes.
Maintained by Datagrove — a Dutch web development agency specializing in fast, well-architected Next.js websites and custom software. We build sites that pass Core Web Vitals and rank. Need an audit or a rebuild? Talk to Datagrove.
MIT — use it, ship it, adapt it.