How to Bypass Next.js Cache Components for Draft Mode Preview

High-traffic Next.js applications often suffer from poor CDN cache hit rates due to how React Server Component payloads are hashed during client-side navigation. This guide uses real performance benchmarks to demonstrate fixes that dramatically improve edge caching efficiency.

If you've recently enabled Cache Components in Next.js 16+ and suddenly noticed your headless CMS preview isn't showing draft content, you're not alone. This is a fundamental conflict between Next.js's aggressive caching strategy and the dynamic nature of content previews.

The traditional draftMode() workflow—which content editors rely on daily—breaks silently when Cache Components enters the picture. Your pages render beautifully fast, but they're serving stale, published content even when draft mode is explicitly enabled.

This guide walks through exactly why Next.js Cache Components draftMode integration requires special handling, and how to implement a robust solution that gives you the best of both worlds: blazing-fast static pages for production users, and live preview for your content team.

The Problem — Cached Components Prevent Editors from Previewing Unpublished Content

Here's a scenario you might recognize: your marketing team is working on a new product launch. They've crafted the perfect blog post in your headless CMS (Sanity, Contentful, Strapi—pick your favorite). They click the "Preview" button expecting to see their draft content, but the page shows the old, published version instead.

The preview URL includes the correct draft token. The __prerender_bypass cookie is set. Yet the content stubbornly refuses to update.

What you're seeing:

// ❌ Broken: This component is cached and ignores draftMode entirely
import { cacheLife } from 'next/cache'
 
async function getPost(slug: string) {

The 'use cache' directive tells Next.js to aggressively cache this component's output. When editors request the preview URL, Next.js serves the cached version—completely bypassing the draft content fetch.

This isn't a bug. It's working exactly as designed. The problem is that Cache Components don't automatically respect draftMode() cookies.

Why This Happens — Cache Components Are Designed to Be Static

To understand the fix, you need to understand what Cache Components actually does under the hood.

When you enable Cache Components (cacheComponents: true in next.config.js), Next.js fundamentally changes how it renders your routes. It prerenders a static HTML shell at build time, with placeholders for dynamic content wrapped in <Suspense> boundaries.

From the official Next.js documentation:

Cache Components eliminates these tradeoffs by prerendering routes into a static HTML shell that's immediately sent to the browser, with dynamic content updating the UI as it becomes ready.

The key insight: components marked with 'use cache' are rendered during build time (or cached on first request), not on every request.

The draftMode() function relies on reading a cookie from the incoming request:

But here's the conflict: when your data-fetching function is wrapped with 'use cache', it executes before the request context is established. The cache layer has no concept of cookies, headers, or any request-specific data.

This behavior is explicitly documented as a core design principle. As noted in GitHub issue #86739, accessing runtime data like cookies(), headers(), params, or searchParams within cached scopes triggers warnings because these values simply aren't available in that context.

The cache layer is intentionally request-agnostic. That's what makes it fast. But it also means Next.js Cache Components draftMode don't work together out of the box.

The Solution — Implement a Conditional Check to Bypass the Cache Layer

The fix is straightforward once you understand the problem: check draftMode().isEnabled before entering any cached scope, and conditionally skip the cache when previewing.

Here's the corrected pattern:

The key changes:

1. Check draftMode() at the component level — before calling any cached functions
2. Create separate functions for cached vs. uncached data fetching
3. Conditionally route to the appropriate function based on isEnabled

This pattern ensures that:

• Production traffic hits the optimized cache path
• Editors with draft cookies get live, uncached content
• The cache remains valid (no cache pollution from draft content)

Why Not Use 'use cache: private'?

You might wonder if 'use cache: private' is the answer here. It's not—at least not for this use case.

The 'use cache: private' directive does allow access to runtime data like cookies() and headers(), but the results are cached only in the browser's memory and don't persist across reloads. This creates poor UX for editors who need consistent preview behavior.

More importantly, 'use cache: private' is still experimental and depends on runtime prefetching features that aren't stable yet. The conditional bypass pattern shown above is production-ready and works reliably across all Next.js 16+ versions.

Prevention — Creating a Reusable Data-Fetching Wrapper

Sprinkling conditional logic throughout your codebase gets messy fast. Instead, create a centralized wrapper that handles the cache/draft logic in one place.

Here's a production-ready pattern:

Now your page components stay clean:

Handling Parameterized Fetchers

If your fetcher needs parameters (like a slug), modify the wrapper slightly:

This pattern scales to any number of CMS queries while keeping the Next.js Cache Components draftMode logic consolidated.

Bonus: Visual Draft Indicator

Content editors often lose track of whether they're in preview mode. Add a persistent indicator:

Include this in your root layout and editors will always know their preview state.

Key Takeaways

• Cache Components don't respect draftMode() cookies automatically — the 'use cache' directive executes before request context is available
• Check draftMode().isEnabled before entering cached scopes — route to uncached functions when previewing
• Don't rely on 'use cache: private' for preview — it's experimental and doesn't persist across reloads
• Create a reusable wrapper — centralize the draft/cache logic to keep your data layer clean
• Add visual indicators — help editors confirm they're viewing draft content

Next Steps

1. Audit your data layer — identify all 'use cache' functions that fetch preview-able content
2. Implement the wrapper pattern — start with your most-used fetchers
3. Test the full preview flow — enable draft mode and verify fresh content appears
4. Set up cache tags — use cacheTag() and revalidateTag() for granular invalidation when content publishes
5. Monitor for edge cases — check nested layouts and parallel routes for additional cache boundaries

For the full discussion on Cache Components and runtime data access patterns, see GitHub issue #86739—it includes additional context on blocking patterns and workarounds from the Next.js team.