Frontend Performance

How to Fix a 500ms Hydration Task in the Next.js App Router

This walkthrough sits under Hydration & Partial Rehydration Strategies, part of JavaScript Bundle Optimization & Code Splitting. The App Router's promise is that server components ship no JavaScript, so hydration should be cheap. In practice one 'use client' directive placed too high converts the entire subtree beneath it into client components, and you are back to hydrating the whole page — with a 500–900ms task on a throttled profile and an INP that fails the 200ms threshold.

Rapid Diagnosis: Find the Boundary That Swallowed the Tree

  • Look at the long task, not the bundle size. Record a throttled load; the hydration task appears as one long block shortly after first paint, containing hydrateRoot in its stack.
  • Count client components. Any module with 'use client' at the top, plus everything it imports, is a client component. A layout or a provider wrapper with the directive is the usual offender because everything renders inside it.
  • Read the RSC payload size. View source and find the inline self.__next_f.push flight data. Over ~100KB is a signal that large props or serialised data are travelling to the client.
  • Check for a context provider at the root. Theme, auth, i18n and analytics providers are frequently client components wrapping {children}, which is exactly the pattern that keeps the subtree on the server — unless the provider also renders the children through client code.
Where the client boundary sits decides what hydrates In the first tree the directive is on the layout so all nine nodes hydrate; in the second it is on two leaves so only those two hydrate and the rest stay server-rendered HTML. One directive, two very different pages 'use client' on the layout Layout Header Article Footer Nav Prose Links 9 components hydrate — 620ms 'use client' on two leaves Layout Header Article Footer Nav menu Prose Share 2 components hydrate — 40ms

Root Cause Analysis

1. A client boundary too high in the tree. 'use client' marks a module and everything it imports as client code. Placing it on a layout, a page, or a shared wrapper converts the whole route. This is the dominant cause and usually the only one that matters.

2. Providers that render children through client code. A provider can be a client component while its children stay server components — but only if the children are passed as the children prop from a server parent. Importing and rendering them inside the client module instead pulls them across the boundary.

3. An oversized flight payload. Every prop crossing from server to client is serialised into the HTML. Passing a fully expanded list of 500 records to a client table means downloading it twice — once as HTML, once as flight data — and parsing the second copy on the main thread before hydration starts.

4. Barrel imports dragging in client modules. An index.ts that re-exports fifty components means importing one client component from it can pull the rest of the barrel into the client graph, inflating both the bundle and the hydrated tree.

Step-by-Step Resolution

1. Push the directive to the leaves. Keep layouts and pages as server components; mark only the interactive controls.

tsx
// app/layout.tsx — NO 'use client'
import { MobileNavToggle } from '@/components/mobile-nav-toggle';   // client leaf
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en"><body>
      <header><nav>{/* static markup */}<MobileNavToggle /></nav></header>
      {children}
    </body></html>
  );
}
// trade-off: leaf-level boundaries mean more small client chunks and slightly
// more request overhead than one big one. That is a good trade below a few
// dozen islands; past that, group related controls into one client module.

Expected outcome: the hydrated component count drops by an order of magnitude; the hydration task typically falls from 600ms to under 80ms.

2. Pass children through, do not import them. This is the pattern that lets a client provider wrap server content.

tsx
'use client';
// components/theme-provider.tsx — a client component that keeps children server-side
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState('light');
  return <ThemeCtx.Provider value={{ theme, setTheme }}>{children}</ThemeCtx.Provider>;
}
// Used from a SERVER component:
//   <ThemeProvider><ServerPage /></ThemeProvider>
// trade-off: server children cannot consume the client context. Anything that
// truly needs the value must itself be a client component — keep those small
// and push them to the leaves too.

Expected outcome: providers stay interactive while the content they wrap ships zero JavaScript.

3. Shrink what crosses the boundary. Send the minimum a client component needs, and let it fetch or compute the rest.

tsx
// Before: the whole dataset is serialised into the HTML twice.
// <DataTable rows={allRows} />                     // 380KB of flight data

// After: render the table as HTML on the server, hydrate only the controls.
export default async function Page() {
  const rows = await getRows();
  return (
    <>
      <TableFilters defaultSort="name" />           {/* client, tiny props */}
      <table>{rows.map((r) => <Row key={r.id} {...r} />)}</table>  {/* server */}
    </>
  );
}
// trade-off: client-side sorting now needs either a server round trip or a
// re-fetch. For tables under a few hundred rows that is usually faster than
// shipping and parsing the data twice — measure both on a throttled profile.

Expected outcome: flight payload drops sharply; parse time before hydration falls with it.

4. Defer the client components that are not immediately needed. Use next/dynamic for below-the-fold interactive widgets so their chunk and their hydration both wait.

tsx
const Comments = dynamic(() => import('@/components/comments'), {
  loading: () => <div style={{ minHeight: 420 }} />,   // reserve the box
});
// trade-off: ssr defaults to true here, which keeps the server HTML. Setting
// ssr:false removes the markup entirely — faster, but it costs you the content
// in the initial HTML and risks a layout shift when it appears.

Expected outcome: removes the widget's chunk from the critical path without losing its server-rendered content.

Verification

Re-record the throttled load and compare the hydration task directly. A successful fix shows no single task above 50ms in the window between first paint and interactivity, and the flame graph shows short, separated hydration blocks rather than one continuous one.

Check the build output too — Next.js reports the First Load JS per route, and pushing boundaries down should reduce it measurably:

bash
next build
# Route (app)                    Size     First Load JS
# ┌ ○ /                          1.8 kB          96 kB   ← was 214 kB
# trade-off: First Load JS counts bytes, not hydration cost. A route can shrink
# in bytes while still hydrating hundreds of components — always confirm with a
# trace, not with the table alone.

Then verify in the field. Segment INP by interactions that happened within two seconds of navigation: that population is the one paying the hydration cost, and it should improve first and most. Site-wide p75 follows more slowly, in proportion to how many sessions interact early.

FAQ

Does 'use client' mean the component is not server-rendered?

No. Client components are still rendered to HTML on the server; the directive controls whether they are also hydrated on the client and whether their code is shipped. That is why a page full of client components still paints fast and still fails INP — the markup arrives early, the JavaScript to make it interactive arrives and executes later.

Should I set ssr: false on dynamic imports to cut hydration?

Only for components whose content is genuinely not needed in the initial HTML — a chart that requires a browser-only library, for instance. ssr: false removes the server markup, so you lose the content for crawlers and for the first paint, and you usually introduce a layout shift when the component finally mounts. Prefer keeping SSR and deferring hydration instead.

How do I find which import pulled a module into the client bundle?

Trace the import chain from any client entry point in the build's module graph — the bundle analyser output shows which client chunk contains the module and what imports it. The most common surprise is a barrel file: importing one client component from an index.ts can pull in siblings that were meant to stay on the server. Import from the concrete module path instead.

How do I audit which components are client components?

Search the source for the directive and then follow the imports, because the boundary is transitive: every module a client module imports joins the client graph. A directive count alone understates the blast radius. The reliable check is the build's client bundle contents — if a component you believed was server-only appears there, something imported it across the boundary, and the import chain will show you what.

Are server components always faster?

For rendering, they remove client work entirely, which is unambiguously good. What they add is data-fetching latency on the server and a serialised payload travelling to the client, so a server component that fetches slowly can delay the whole response while a client component would have painted a shell first. The right split is by interactivity, not by a belief that one kind is faster: static content on the server, controls on the client, and data fetched wherever it is fastest.

Does streaming remove the need to move the boundary?

It changes when the cost is paid, not how much there is. Streaming with Suspense lets parts of the page arrive and hydrate independently, so no single task blocks everything — a genuine improvement to interaction latency. But the same components still hydrate, so total blocking time barely moves. Use streaming to make a large tree feel responsive, and boundary placement to make the tree smaller.