nextjs-client-audit

A Claude Code Skill that finds every unnecessary "use client" in a Next.js App Router project, shows what each one costs, and gives you a safe, concrete fix built from your own code.

English · العربي

---

English

Repository layout

nextjs-client-audit/          ← this repo
├── nextjs-client-audit/      ← the Skill (copy this folder into ~/.claude/skills/)
├── dist/nextjs-client-audit.skill   ← packaged Skill (also attached to each Release)
└── docs/index.html           ← the showcase site (GitHub Pages)

Live site: https://radyelkasas.github.io/nextjs-client-audit/

Why

"use client" is not a switch that makes an error go away. It is a boundary: the file and everything it imports is shipped to the browser, downloaded, parsed and hydrated. One directive at the top of a page can quietly turn the whole page tree into client JavaScript.

Ask Claude "why is my page heavy?" or "audit use client" and this skill:

1. Finds every "use client" that is a real directive, and ignores the same text in comments, strings and code samples. It also flags directives written after the imports, which Next.js silently ignores.
2. Checks if each one is needed: React state/effect hooks, Next.js client hooks, event handlers, function props, browser APIs, client-only libraries, client-only custom hooks (it opens the hook's file), next/dynamic with ssr:false, createContext, class components.
3. Measures the boundary: it builds the import graph (tsconfig paths aliases included) and counts how many modules each boundary drags into the client bundle. This is an estimate in modules, clearly labelled, never presented as bytes.
4. Classifies the fix:

Fix	When
REMOVE	The file uses nothing client-only. Delete the directive.
PUSH_DOWN	Move "use client" to the smallest child that needs it: a child file, an extracted form, a hook moved into the one leaf that uses it, or a small client "shell" for shared state.
CHILDREN_PATTERN	Keep a thin client wrapper (a Modal) and pass the heavy server content in as children.
MOVE_FETCH	The component is client only to fetch data in useEffect / useQuery. Make it an async Server Component.

5. Writes the report: a summary, a priority table, Before/After code for the top 3 findings using your real code, and how to verify with next build.

Trustworthy by design

• Read-only. The audit never edits files. Claude applies a fix only after you say yes, one fix at a time.
• Honest about uncertainty. If it cannot be sure, the finding says Needs manual check and what would settle it. Examples: an unknown use* hook from a package, a third-party component whose package does not declare "use client", an import it could not resolve.
• Checks third-party packages. Before it says a shadcn/Radix wrapper can lose its directive, it opens the installed package and confirms the package ships its own "use client".
• Fixes that actually shrink the bundle. A child is only suggested for children if it does not use the wrapper's state and is not already in the client bundle through another component.
• Accurate about layouts. A client layout ships its own imports on every page under it, but pages passed in as {children} stay Server Components. The report says exactly that.
• Risk notes next to the fixes that can change behaviour. For example: MOVE_FETCH changes when data loads, and a relative fetch("/api/…") won't work on the server.

Install

Claude Code (recommended)

git clone https://github.com/radyelkasas/nextjs-client-audit.git
mkdir -p ~/.claude/skills
cp -R nextjs-client-audit/nextjs-client-audit ~/.claude/skills/

Or download nextjs-client-audit.skill from Releases and unzip it into ~/.claude/skills/ (a .skill file is a zip):

unzip nextjs-client-audit.skill -d ~/.claude/skills/

For one project only, put the folder in <your-project>/.claude/skills/ instead.

Claude.ai: Settings → Capabilities → Skills → upload nextjs-client-audit.skill.

Requires Node.js 18+. No dependencies: it uses the typescript (or @babel/parser) already installed in your Next.js project, and falls back to a careful regex scan, with a warning, if neither is there.

Try it

Open your Next.js project in Claude Code and ask:

audit use client in this project

Or "why is my dashboard bundle so big?", "check my client components", "review Server vs Client components".

You can also run the script directly:

node ~/.claude/skills/nextjs-client-audit/scripts/audit.js . --format md      # Markdown report
node ~/.claude/skills/nextjs-client-audit/scripts/audit.js . --json audit.json # machine-readable JSON

Exit codes: 0 audit ran · 2 not an App Router project · 1 error.

Config (optional)

Add .client-audit.json to your project root to teach it your own libraries:

{
  "clientLibraries": { "@acme/motion": "any", "acme-flags": "hooks" },
  "serverSafeHooks": ["useFeatureFlag"],
  "extraScanDirs": ["src/features"],
  "ignore": ["src/legacy/**"]
}

See references/rules.md for every rule and the reasoning behind it, and references/patterns.md for Before/After examples of each fix.

What's inside

nextjs-client-audit/
├── SKILL.md               instructions Claude follows (when to run, how to verify, how to present)
├── scripts/audit.js       the analyzer (Node.js, zero dependencies, JSON or Markdown output)
├── references/rules.md    Server vs Client rules, with reasoning
├── references/patterns.md Before/After for every fix type
├── tests/fixtures/        3 small Next.js projects + a Pages Router control
└── tests/run-tests.js     runs the audit on every fixture with every available parser

Tests

node tests/run-tests.js

This is the beginning of the README. Read the rest at the original. Read the full README ↗