Next.js Optimizer

---
name: nextjs-optimizer
description: |
  Trigger when the user asks to optimize a Next.js app, improve Core Web Vitals,
  reduce bundle size, or speed up builds. Phrases: "Next.js performance",
  "bundle size", "Core Web Vitals", "LCP", "optimize Next".
allowed-tools:
  - Read
  - Bash(npx next build *)
  - Bash(npx @next/bundle-analyzer *)
  - Grep
---

# Next.js Optimizer

Audit a Next.js app against the current performance playbook: bundle size,
Core Web Vitals, and build time. App Router specific (Next 13+).

## Prerequisites

- Next.js 13+ with App Router
- Running app with production build (`next build && next start`)

## Steps

1. **Run the bundle analyzer:**
   ```bash
   ANALYZE=true pnpm build
   ```

   Look for:
   - Client bundles over 200 KB gzipped per route
   - Large deps pulled into client that could be server-only
   - Duplicate copies of dependencies

2. **Audit `"use client"` boundaries.** Grep for `"use client"` at the top
   of files. For each, ask:
   - Does this component actually need client-side state or effects?
   - Can the client-side surface be smaller (extract the stateful button,
     keep the rest server)?

3. **Check image usage.** Every `<img>` that is not `next/image` is an LCP
   and bandwidth bug. Replace with `<Image>` and supply width/height.

4. **Audit font loading.** Use `next/font` for every web font. Inline
   `<link rel="stylesheet">` from Google Fonts blocks render.

5. **Split heavy client code with `next/dynamic`:**
   ```tsx
   const Heavy = dynamic(() => import("./heavy-chart"), { ssr: false });
   ```

6. **Enable Turbopack for dev and build** if not already:
   ```bash
   next dev --turbo
   next build --turbo
   ```

7. **Run Lighthouse against a production build on a preview deploy.** Not
   dev server, not localhost. Target: LCP < 2.5s, INP < 200ms, CLS < 0.1.

## Quick wins to check first

- `"use client"` at the root layout (client-ifies the whole app)
- `import _ from "lodash"` instead of named imports (pulls in full lib)
- Missing `revalidate` or `dynamic = "force-dynamic"` decisions on fetch
  calls, causing unintended static or dynamic behavior
- Client component re-rendering because a server-passed prop is a new
  reference every render

## Output

- Bundle analyzer report link and top 5 largest chunks called out
- Before/after Core Web Vitals measurements
- PR with the 2-3 highest-impact fixes
- Note on any issue that needs architectural change rather than point fix