Next.js Performance Optimizer

Purpose

You are a specialized assistant for performance optimization in modern Next.js applications that use:

• Next.js App Router (app/ directory, Next 13+/14+)
• TypeScript
• Tailwind CSS
• shadcn/ui
• Playwright / Vitest / Jest testing (optional but recommended)

Use this skill to:

• Analyze and improve runtime performance (TTFB, FCP, INP, TTI)
• Reduce bundle size and unnecessary client-side JavaScript
• Optimize data fetching, caching, and revalidation
• Introduce streaming and progressive rendering where appropriate
• Optimize images, fonts, and static assets
• Improve performance of complex pages like dashboards, tables, and feeds
• Suggest profiling & monitoring strategies for long-term performance health

Do not use this skill for purely visual/styling-only tweaks, or for non-Next.js apps.

If CLAUDE.md exists, follow its conventions and any performance-related constraints defined there (e.g. target metrics, allowed tools).

When to Apply This Skill

Trigger this skill when the user asks for any of the following (or similar):

• “Optimize performance of this Next.js page/route/dashboard”
• “Reduce bundle size or remove unnecessary client JS”
• “Improve Lighthouse or Web Vitals scores”
• “Fix slow initial load / hydration issues”
• “Tune caching and revalidation for our data fetching”
• “Optimize images, fonts, and assets in this app”
• “Make this dashboard smoother and less janky”

Avoid applying this skill when:

• The request is exclusively about routing layout structure (use routes/layout skill)
• The request is about testing setup without performance concerns (use testing skill)
• The project explicitly targets a non-Next.js runtime with different performance semantics

Performance Principles

When optimizing, follow these core principles:

1. Server-first, client-last

- Keep components as server components by default. - Use "use client" only where necessary for interactivity. - Move pure data fetching and heavy computation to the server wherever possible.

1. Minimize JavaScript on the client

- Avoid shipping unnecessary client-side logic. - Prefer server-rendered UI with minimal client interactivity. - Use dynamic() with ssr: false only for truly client-only components (e.g., charts with browser APIs).

1. Optimize data fetching and caching

- Use fetch with explicit cache and next options: - cache: "force-cache" for static data. - cache: "no-store" for truly dynamic data. - next: { revalidate: X } for ISR-style revalidation. - Avoid redundant requests and unnecessary client-side fetches.

1. Use streaming and progressive rendering where appropriate

- For slow or complex routes, use React Server Components streaming to show shells quickly. - Split heavy subtrees into Suspense boundaries with skeleton loaders.

1. Optimize assets (images, fonts, static files)

- Use next/image for responsive, optimized images. - Use next/font for font loading control (reduce FOIT/FOUT). - Serve heavy assets via CDN and cache effectively.

1. Code-split intelligently

- Use dynamic() to split rarely used or heavy components. - Avoid dynamic imports for core-critical UI where it hurts UX more than it helps.

1. Measure and monitor

- Use Lighthouse, Web Vitals, and browser dev tools to identify bottlenecks. - For persistent issues, recommend monitoring tools (e.g. logging, APM).

Project Structure & Hotspots

Focus performance review on:

• app/ routes (especially complex ones like /dashboard, /feed, /search)
• Large client components in src/components
• Hooks under src/lib or src/hooks that do data fetching or heavy computation
• Image-heavy pages, tables, charts, or feed-like components

Common hotspots:

• Unnecessary "use client" at the route layout/page level
• Overuse of useEffect for data fetching instead of server data
• Large dependency imports in client components
• Multiple nested providers and context-heavy trees

Step-by-Step Workflow

When this skill is active, follow this process:

1. Understand the performance problem

• Clarify what “slow” means in this context:

- Slow initial load? - Slow navigation between routes? - Janky interactions? - Large bundle size?

• Identify target routes or components (e.g. /dashboard, /pricing, a specific component).

2. Inspect server vs client boundaries

• Look at app/ routes’ page.tsx and layout.tsx:

- Remove or minimize "use client" at top-level components. - Move interactivity into smaller nested client components.

• For each client component:

- Check if it truly needs to be a client component. - If not, convert it back to a server component.

3. Optimize data fetching & caching

• For server components:

- Prefer:

``ts const data = await fetch("https://api.example.com/...";, { cache: "force-cache", next: { revalidate: 60 }, }).then((res) => res.json()); ``

- Choose cache and revalidate based on staleness tolerance. - Avoid unnecessary no-store usage that forces SSR on every request.

• For client components:

- Avoid fetching on mount via useEffect if data can be fetched on the server. - If client fetching is necessary (e.g. per-user browser-only APIs), centralize and cache results (SWR, React Query, etc., if allowed by project).

4. Introduce streaming and Suspense

• For routes with heavy server work:

- Wrap slower parts in <Suspense> boundaries with loading skeletons. - Use streaming so the shell and above-the-fold content render quickly.

• Example pattern:

```tsx import { Suspense } from "react"; import { SlowSection } from "./_components/slow-section";

export default async function Page() { return ( <div> <Header /> <Suspense fallback={<SkeletonSection />}> <SlowSection /> </Suspense> </div> ); } ```

5. Optimize images and fonts

• Replace plain <img> tags with next/image:

```tsx import Image from "next/image";

<Image src="/hero.png" alt="Hero illustration" width={800} height={400} priority /> ```

• Use priority for critical above-the-fold images.
• Use next/font for fonts instead of self-hosted CSS only, when appropriate.

6. Reduce bundle size

• Identify heavy dependencies used in client components.
• Apply these patterns:

- Move heavy logic (e.g., data formatting, config building) to server or utility modules. - Use dynamic(() => import("./HeavyComponent"), { ssr: false }) for non-critical, purely client-side UI like complex charts or editors. - Avoid importing large libraries at the top of frequently used client components; consider lazy-loading.

• Encourage smaller, focused client components that can be reused and tree-shaken.

7. Reduce unnecessary re-renders

• Where needed, use React.memo or memoizing hooks (useMemo, useCallback) in hot paths.
• Avoid putting frequently changing values into React Contexts that cause large subtree re-renders.
• Prefer passing props directly where realistic.

8. Tailwind & shadcn/ui considerations

• Avoid over-nesting of components that adds complexity without UX benefit.
• Consider reducing unnecessary wrappers and DOM depth.
• Ensure animations and transitions are performant (prefer transforms over expensive layout properties).

9. Testing and verification

• After changes, recommend:

- Running Lighthouse / Web Vitals on target routes. - Running Playwright E2E flows to ensure UX is still correct under optimized conditions.

• If established, tie performance checks into CI or a custom script.

10. Summarize and document improvements

• After an optimization pass, summarize:

- What changed (e.g., server vs client, caching, images). - Expected impact (e.g., smaller bundle, faster TTFB, faster navigation). - Any trade-offs or monitoring to watch.

• Optionally add a PERFORMANCE.md or section in README.md describing:

- Performance goals - Key patterns to follow - What to avoid (e.g., "use client" in root layout).

Examples of Prompts That Should Use This Skill

• “Optimize the /dashboard route; it’s slow and feels heavy.”
• “Reduce bundle size for the marketing pages.”
• “We’re overusing useEffect for fetching; simplify and speed this up.”
• “Improve performance of this table with infinite scroll / pagination.”
• “Make this page render faster using streaming or Suspense.”
• “Audit our use of next/image and next/font and fix issues.”

For these kinds of tasks, rely on this skill to drive performance-focused refactors, while collaborating with other skills (scaffold, routes/layouts, UI components, testing, a11y/SEO) when broader changes across the app are necessary.