Next.js App Router Client Directive Auditor

Description

--- ⚠️ AI-Generated Skill Generated by MFKVault on 2026-05-13. Review before use. Not professional advice. Modify as needed for your use case. --- --- name: Next.js App Router Client Directive Auditor description: Audits Next.js App Router projects to identify missing 'use client' directives and provides specific code snippets to fix server/client boundary violations. --- # Next.js App Router Client Directive Auditor ## When to use this skill Use this skill when reviewing Next.js App Router codebases for correct server/client component separation. Trigger this when a user reports hydration mismatches, "document is not defined" errors, browser API usage in server components, or asks for an audit of their component structure. This skill is particularly valuable during code reviews and when debugging production issues related to component boundaries. ## Key behaviors - Identify files that use client-only APIs (useState, useEffect, useContext, useRef, event handlers, browser APIs like window, localStorage, document) without 'use client' directive - Provide exact line numbers and code snippets showing the problematic code - Generate specific 'use client' directive placement recommendations with corrected code examples - Suggest refactoring patterns to move client-only logic into separate client components when appropriate - Explain why each violation occurs and the consequences (hydration errors, runtime failures, etc.) - Recommend architectural improvements to properly separate server and client concerns - Include performance implications of marking components as client components ## Examples ### Example 1: useState without 'use client' **User Request:** "I'm getting hydration errors on my components. Can you audit this file?" **File Content:** ```javascript // app/components/Counter.tsx import { useState } from 'react'; export default function Counter() { const [count, setCount] = useState(0); return <button onClick={() => setCount(count + 1)}>{count}</button>; } ``` **Response:** ``` AUDIT RESULT: Missing 'use client' directive Issue on lines 2-3: - useState hook imported and used without client directive - onClick event handler requires client component CORRECTED CODE: 'use client'; import { useState } from 'react'; export default function Counter() { const [count, setCount] = useState(0); return <button onClick={() => setCount(count + 1)}>{count}</button>; } Impact: Without this directive, you'll experience hydration mismatches where the server renders one version and the client renders another. ``` ### Example 2: localStorage access in server component **User Request:** "I need to check if my dashboard component has client boundary issues." **File Content:** ```javascript // app/dashboard/page.tsx export default function DashboardPage() { const theme = localStorage.getItem('theme') || 'light'; return <div className={theme}>{/* content */}</div>; } ``` **Response:** ``` AUDIT RESULT: Browser API without 'use client' Issue on line 2: - localStorage accessed in server component - localStorage is undefined during server-side rendering REFACTORED SOLUTION: Create a separate client component: // app/dashboard/ThemeProvider.tsx 'use client'; import { useEffect, useState } from 'react'; export function ThemeProvider({ children }) { const [theme, setTheme] = useState('light'); useEffect(() => { setTheme(localStorage.getItem('theme') || 'light'); }, []); return <div className={theme}>{children}</div>; } // app/dashboard/page.tsx import { ThemeProvider } from './ThemeProvider'; export default function DashboardPage() { return ( <ThemeProvider> {/* Your content here */} </ThemeProvider> ); } Benefits: Server component remains on server (better performance), client logic isolated, hydration-safe. ``` ### Example 3: useContext without directive **User Request:** "My app crashes with 'useContext requires client component' error. Can you help?" **File Content:** ```javascript // app/components/UserProfile.tsx import { useContext } from 'react'; import { UserContext } from '@/context/UserContext'; export default function UserProfile() { const user = useContext(UserContext); return <div>Welcome, {user.name}</div>; } ``` **Response:** ``` AUDIT RESULT: Hook usage without 'use client' Issue on lines 3-5: - useContext hook called in server component - UserContext is a client-side concern CORRECTED CODE: 'use client'; import { useContext } from 'react'; import { UserContext } from '@/context/UserContext'; export default function UserProfile() { const user = useContext(UserContext); return <div>Welcome, {user.name}</div>; } Note: Ensure UserContext provider is also marked 'use client' at the top of your context file. ``` ## What NOT to do - Don't mark entire page files as 'use client' without reason; keep pages on server when possible - Don't ignore layout components that wrap multiple pages; analyze what actually requires client behavior - Don't assume all components need 'use client' just because they're interactive; only interactive elements and hooks need it - Don't place 'use client' in the middle of a file; it must be at the very top before other imports - Don't overlook that 'use client' boundaries affect entire subtrees; child components inherit the directive - Don't forget that server-only libraries (databases, secrets) cannot be used below 'use client' boundaries - Don't miss event handlers like onClick, onChange, onSubmit; these require 'use client' ## Edge cases **Conditional hooks:** If you use hooks conditionally or dynamically, the entire component must be 'use client', even if the hook isn't always executed. React's rules of hooks require consistent hook ordering. **Mixed imports:** When a file imports both server-only packages and client hooks, mark as 'use client' and move server logic to separate server-only files using 'use server' or API routes. **Context providers:** Provider components need 'use client', but the context file itself doesn't. The value passed through context can be server data, but consuming it requires a client component. **useEffect initialization:** Sometimes developers use useEffect just to initialize state from localStorage. Recommend using a library like `next-safe-action` or restructure to pass initial state from server instead. **Third-party libraries:** Many UI libraries (shadcn, Radix UI components) are already marked 'use client'. You don't need to add the directive again; the bottom-most directive takes precedence. **Dynamic imports:** When using `dynamic()` with `ssr: false`, the component is automatically client-side, but still explicitly mark it with 'use client' for clarity. ---

Security Status