cacheComponents and theming #93689

MakakWasTaken · 2026-05-08T12:18:29Z

MakakWasTaken
May 8, 2026

Summary

I have recently run into a dilemma regarding cacheComponents. I would like to cache as much of my platform to improve performance. This has lead me to start introducing use cache on a lot of pages.

Option A
I can use use cache: private, but doesn't that defeat the purpose of caching to some extent, since my user won't visit that same page multiple times.

Option B
I can add a Suspense to my root layout, but I wouldn't that cause the rendering to be postponed until the headers have loaded?

The solution I would like is to prerender depending on known states of a cookie or header. Something similar to how generateStaticParams work. Or just another solution for better handling prerendering and caching for theming.

Additional information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.3.0: Wed Jan 28 20:56:35 PST 2026; root:xnu-12377.91.3~2/RELEASE_ARM64_T6030
  Available memory (MB): 18432
  Available CPU cores: 11
Binaries:
  Node: 24.15.0
  npm: 11.12.1
  Yarn: 4.13.0
  pnpm: N/A
Relevant Packages:
  next: 16.2.6
  eslint-config-next: N/A
  react: 19.2.6
  react-dom: 19.2.6
  typescript: 6.0.3
Next.js Config:
  output: standalone

Example

No response

salvador-castro · 2026-05-08T14:41:47Z

salvador-castro
May 8, 2026

The pattern you're looking for is to read the cookie/header outside the cached scope, then pass it as an argument to the cached component. Next.js uses the arguments as part of the cache key, so each theme variant gets its own cache entry — shared across all users with that theme.

// layout.tsx or page.tsx (not cached — reads runtime data)
import { cacheLife } from 'next/cache'
import { cookies } from 'next/headers'
import { Suspense } from 'react'

export default async function Layout({ children }) {
  const theme = (await cookies()).get('theme')?.value ?? 'light'
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <ThemedShell theme={theme}>{children}</ThemedShell>
    </Suspense>
  )
}

// Cached per theme value — 'light' and 'dark' are separate cache entries
async function ThemedShell({ theme, children }) {
  'use cache'
  cacheLife('days')
  return <div className={`theme-${theme}`}>{children}</div>
}

This way you get shared server-side cache per theme (not per user), the Suspense handles the runtime boundary cleanly without blocking the static shell, and you avoid use cache: private entirely.

If your themes are finite and known upfront, you can also prerender all variants at build time using generateStaticParams — but for cookie-based theming the pattern above is the idiomatic approach.

0 replies

icyJoseph · 2026-05-12T23:25:03Z

icyJoseph
May 12, 2026
Collaborator

For now, you can try with either of these (favoring the first one).

Single prerender, client paints theme

One static HTML per page. An inline <script> reads the cookie and adds the class to <html> before paint. Toggle is client-only: write cookie, swap class. No router involvement.

For server-rendered toggle state (e.g. button disabled), a second inline script placed after the SSR'd buttons patches .disabled during HTML parsing. useId keeps the selector stable; on the client the script is re-rendered with type="text/plain" so React doesn't complain about scripts in component trees.

Prerender once for both themes
Switching is a class swap.

However...

Load-order matters: parse → script → paint → hydrate. Break any of those and you get flashes.
suppressHydrationWarning on <html>, on the buttons, on the patch <script>.
No JS = default theme.

Prerender per known theme

generateStaticParams returns the theme list. Pages live under [theme]/. A proxy rewrites /foo → /<cookie>/foo server-side, and redirects direct visits to /light or /dark back to the unprefixed path so themed URLs aren't shareable.

Each route ends up with one cache slot per theme.

HTML arrives themed. No FOUC, no JS required.
Server can branch on theme, that is, RTL, different components, distinct meta.
No hydration tricks.

But then...

Switching theme is a server round trip, an actual navigation.
Proxy on every request, between you and your CDN.

I think you likely just want the first approach. The second one is more for like, logged-in/out "variants".

https://github.com/icyJoseph/next-theme-prerender

Happy to keep on discussing.

0 replies

wanhei1 · 2026-05-29T17:55:57Z

wanhei1
May 29, 2026

Great question about the cacheComponents + theming dilemma. Here's the recommended pattern:

Best Practice: Read Cookie Outside, Pass as Prop

// app/layout.tsx or middleware
import { cookies } from 'next/headers';

export default async function RootLayout({ children }) {
  // Read theme cookie OUTSIDE the cached scope
  const cookieStore = await cookies();
  const theme = cookieStore.get('theme')?.value || 'light';

  return (
    <html data-theme={theme}>
      <body>
        {/* Pass theme as prop to cached components */}
        <CachedLayout theme={theme}>{children}</CachedLayout>
      </body>
    </html>
  );
}

For Cached Components

// components/CachedLayout.tsx
'use cache: private'

export async function CachedLayout({ theme, children }) {
  // This component is cached per user (private)
  // theme is part of the cache key automatically
  return (
    <div className={`theme-${theme}`}>
      <Header theme={theme} />
      {children}
    </div>
  );
}

Alternative: Hybrid Approach

// Use 'use cache' for the static shell
// Use 'use cache: private' only for user-specific parts

export async function Page() {
  return (
    <CachedStaticShell>
      <UserSpecificThemeWrapper>
        <CachedContent />
      </UserSpecificThemeWrapper>
    </CachedStaticShell>
  );
}

Key Insight

'use cache' (public) = cached globally, shared across users
'use cache: private' = cached per user, respects cookies/headers
Pass cookie values as props to avoid cache key confusion
The cookie/header is read once (cheap), then used in the cache key

This gives you the best of both worlds: static caching for content, per-user caching for theming.

0 replies

PrashantSinghUP64 · 2026-05-31T17:10:38Z

PrashantSinghUP64
May 31, 2026

For theming, I would not try to make the whole page vary by cookie/header if the theme is only visual — that tends to make too much of the tree request-specific.
The usual pattern is:

Keep the page/static data cacheable.
Read the theme cookie in the smallest possible dynamic boundary.
Apply the theme through an attribute/class on or a small client provider.
Cache expensive/shared data separately with use cache.

Example:
tsx// app/layout.tsx
import { cookies } from "next/headers"
import ThemeProvider from "./theme-provider"

export default async function RootLayout({ children }) {
const theme = (await cookies()).get("theme")?.value ?? "system"
return (

{children}

)
}
Keep expensive content independent from the theme:
tsxasync function ProductList() {
"use cache"
const products = await getProducts()
return
}
use cache: private is more useful when the rendered result is genuinely user-specific. For a light/dark theme, it often gives up too much shared caching for something CSS can handle. If the theme affects data/content (not just styling), split the route: cache shared parts publicly, and wrap only the theme-dependent section in a Suspense/dynamic boundary.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cacheComponents and theming #93689

Uh oh!

{{title}}

Uh oh!

Replies: 4 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

cacheComponents and theming #93689

Uh oh!

MakakWasTaken May 8, 2026

Summary

Additional information

Example

Replies: 4 comments

Uh oh!

salvador-castro May 8, 2026

Uh oh!

Uh oh!

icyJoseph May 12, 2026 Collaborator

Single prerender, client paints theme

Prerender per known theme

Uh oh!

wanhei1 May 29, 2026

Best Practice: Read Cookie Outside, Pass as Prop

For Cached Components

Alternative: Hybrid Approach

Key Insight

Uh oh!

PrashantSinghUP64 May 31, 2026

MakakWasTaken
May 8, 2026

salvador-castro
May 8, 2026

icyJoseph
May 12, 2026
Collaborator

wanhei1
May 29, 2026

PrashantSinghUP64
May 31, 2026