nextjs - 💡(How to fix) Fix docs: Document `experimental.cachedNavigations` feature [2 comments, 3 participants]

Description

The experimental.cachedNavigations feature is currently undocumented. After reverse-engineering the Next.js 16.2.1-canary.17 source code, I've compiled a comprehensive understanding of this feature that could benefit the community and warrants official documentation.

What is cachedNavigations?

An experimental feature that enables staged RSC rendering with client-side segment caching. When enabled (requires cacheComponents: true), the server splits RSC Flight responses into static and dynamic stages, allowing the client to cache static portions and serve them instantly on repeat navigations while streaming only the dynamic parts.

Configuration

// next.config.ts
const nextConfig: NextConfig = {
  cacheComponents: true, // Required prerequisite
  experimental: {
    cachedNavigations: true,
  },
};

Also supports environment variable override:

__NEXT_EXPERIMENTAL_CACHED_NAVIGATIONS=true

Key Technical Details Found

1. Staged Rendering Pipeline: When enabled, generateStagedDynamicFlightRenderResult() is called instead of generateDynamicFlightRenderResult(), enabling a multi-stage render (Static → EarlyRuntime → Dynamic) via StagedRenderingController.

2. Marker Byte Protocol: Server prepends a single control byte to RSC Flight response streams:

   • 0x23 (#) = Complete response (fully cacheable)
   • 0x7e (~) = Partial response (has dynamic content)

3. Static Byte Length: Server calculates staticStageByteLength — the byte offset where static content ends, sent as l field in RSC payload for client-side cache boundary detection.

4. StaleTimeIterable: A buffered async iterable that streams per-component stale time values during rendering, enabling granular cache TTL per segment.

5. Client-side: stripIsPartialByte() removes the marker, then stream.tee() branches the response between React rendering and the segment cache for future navigations.

6. Validation: Throws error E1089 if enabled without cacheComponents: true.

Source Files Referenced

Request

Could documentation be added for this feature? Specifically:

1. What it does — Staged RSC rendering with segment caching
2. Configuration — Config option + env var + prerequisites
3. How it works — Marker byte protocol, static/dynamic split
4. When to use it — Performance characteristics and ideal use cases
5. Interaction with other features — staleTimes, prefetchInlining, dynamicOnHover, partialFallbacks

Environment

• Next.js: 16.2.1-canary.17
• Node.js: v25.8.2
• OS: Linux (Debian)

Which area(s) are affected?

Documentation

Additional context

I'm running a production enterprise CMS (LOUST.PRO) on Next.js 16.2 canary and discovered this feature while reviewing the experimental config options. The source code reveals a sophisticated implementation that is clearly functional but has zero documentation. Given that cacheComponents is already stable and promoted to root-level config, cachedNavigations seems like the natural next step that users would want to enable for performance gains.

I've also documented interactions with partialFallbacks (build-time companion), unstable_instant (runtime prefetch integration), and the staleTimes config (TTL control).