Next.js (App Router) performance

Put the boundary in the right place

Default every component to a Server Component; add 'use client' only where interactivity demands it.

• A 'use client' marker turns the whole subtree client-side — push it to the leaves:

// ❌ the entire page ships JS
'use client'
export default function Page() { return <Chart filters={<Filters/>} /> }

// ✅ page stays server; only the leaf is interactive
// page.tsx (server)
export default function Page() {
  return <div><Filters /><Chart /></div>   // Chart.tsx has 'use client'
}

• Server Components can pass serializable props down; never pass functions/classes across the boundary.

Data fetching: know your cache layer

• Static by default; add dynamism explicitly (cookies(), headers(), searchParams make a route dynamic — know which ones you're touching).
• revalidateTag/revalidatePath on writes — invalidation is part of the feature, ship it with the mutation code.

Streaming: suspend below the fold

Wrap slow sections in <Suspense> so the shell ships immediately; the slow data streams in:

export default function Page() {
  return (
    <>
      <Header />                      {/* instant */}
      <Suspense fallback={<Skeleton />}>
        <SlowDashboard />             {/* streams when ready */}
      </Suspense>
    </>
  )
}

Assets

• next/image with correct sizes; LCP image gets priority.
• next/font (self-hosted, no layout shift, no extra request).
• Route-level dynamic = 'force-static' where content is truly static.

Bundle diet (per PR)

1. ANALYZE=1 next build — inspect the client graph.
2. Replace moment/lodash full imports with date-fns/named imports.
3. Icons: import from the icon package's ESM entry or inline SVG — no barrel of 1MB.
4. Heavy editors/charts: next/dynamic with ssr: false and a skeleton.

Meta

• Every route needs generateMetadata (title, description, OG) — it's also your search/snackable surface.
• Parallel data: Promise.all in server components; sequential awaits are the #1 self-inflicted TTFB kill.

Definition of done (agent checklist)

• 'use client' count per route is minimal and leaf-placed
• No fetch waterfalls in server components
• Mutations call the matching revalidate*
• LCP element uses priority image or server-rendered text
• Client bundle diff per PR within budget (see performance-budget skill)