Next.js Cache Components: What Actually Ships to the Browser

Next.js Cache Components: What Actually Ships to the Browser

Next.js Cache Components let you cache React Server Component output at the edge. The mechanism only produces value when the cached fragment stays identical across every user and carries no secrets.

Most teams discover the limits only after the first production incident. A single user-specific field or token inside the component turns the cache into a broadcast channel.

Cache Components require uniform output

If any part of the RSC payload varies by user, the cache either misses constantly or serves the wrong data. We have seen teams cache navigation trees that included role-based menu items. The first user to hit the route set the entry, and subsequent users received menus they should never see.

The rule is simple. Cache only fragments that contain no request headers, cookies, or environment values tied to identity.

Session data breaks the model

Session data reaches the server through cookies or headers. Once it enters a Cache Component, the payload gets stored and reused. We measured one case where cached component output included a user ID in 12 percent of requests after a misconfigured layout.

The fix requires stripping any user context before the component renders. That usually means moving the personalized sections into separate client components or dynamic routes.

Tradeoff between Cache Components and route segments

Two common patterns exist for reducing RSC work.

Cache Components give you fine-grained control inside a single route. They add almost no extra code but demand strict isolation of shared content.

Route segment config with static rendering keeps the entire page static. It requires less discipline around data flow but forces you to split routes when only part of the page is shared.

In practice, Cache Components win when the shared fragment sits inside a larger dynamic page. Route segments win when the whole route qualifies as public.

Failure when a secret reaches the cache

A developer added an internal API token to a cached footer component during a refactor. The token appeared in the serialized RSC payload for every visitor. The incident was caught only after log analysis showed repeated calls from external IPs.

Mitigation now includes a pre-deploy check that scans component props for known secret patterns and rejects the build if any match. The check runs in under four seconds and has caught three similar cases since introduction.

Measuring real cache behavior

Track the ratio of cache hits to total RSC renders for each cached component. A sustained hit rate below 70 percent usually signals that user-specific data has crept in or the fragment changes too often.

Add a simple dashboard that surfaces the top ten components by miss count. Review that list every two weeks and either remove the cache wrapper or move the varying data out.

Final takeaway

Apply Cache Components only to fragments that every user receives unchanged and that contain no secrets.