[Cache Components] Is Next.js's bfCache a back/forward cache?

[koichik]

The docs says:

When the cacheComponents flag is enabled, Next.js uses React's component to preserve component state during client-side navigation.

Internally, this feature seems to be called bfCache. However, I believe the cache behavior differs from the browser's bfCache.

Here is the demo repository:
https://github.com/koichik/bfcache-demo

1. run pnpm dev (or pnpm build and pnpm start).
2. open http://localhost:3000/.

Browser's bfCache

3. click "MPA Counter".
4. click "+" button, you'll see "Count: 1".
5. click "MPA Blank".
6. click "MPA Counter", you'll see "Count: 0".
7. click "+" button twice, you'll see "Count: 2".
8. browser back twice, you'll see "Count: 1".
9. click "+" button twice, you'll see "Count: 3".
10. browser forward twice, you'll see "Count: 2".

This is the back/forward cache behavior.

Next.js's bfCache

11. click "SPA Couter.
12. click "+" button, you'll see "Count: 1".
13. click "SPA Blank".
14. click "SPA Counter", you'll see "Count: 1" (unexpected).
15. click "+", you'll see "Count: 2".
16. browser back twice, you'll see "Count: 2" (unexpected).
17. click "+", you'll see "Count: 3".
18. browser forward twice, you'll see "Count: 3" (unexpected).

This behavior differs from the browser's bfCache.

---

The bfCache should be associated with history entries. In other words, the cache key should be the position of the entry in the history (e.g. window.navigation.currentEntry.key). However, Next.js's bfCache seems to just use the URL as a key. Thus, I don't think this can be called bfCache.

Do you have a plan to implement behavior similar to the browser's (i.e. true) bfCache?

[KrishnaSaxena108]

Yeah, you’re right — what Next.js calls “bfCache” isn’t the same as the browser’s actual back/forward cache.

Browser bfCache is tied to history entries, so when you go back/forward, it restores the exact page state for that specific entry. That’s why your MPA example resets and replays state depending on navigation.

What Next.js is doing with cacheComponents is different — it’s more like keeping React component instances alive across client-side navigations. So instead of restoring per history entry, it just reuses the same component state as long as the route matches.

That’s why in your SPA example:

• state doesn’t reset when navigating away and back
• back/forward doesn’t behave like real bfCache

So yeah, it’s closer to a component-level cache keyed by route, not a true history-based cache.

I don’t think it’s meant to replicate browser bfCache exactly — more like a performance optimization to avoid re-rendering and preserve state during SPA navigation.

Not sure if there are plans to align it with real bfCache behavior, but that would probably require deeper integration with the browser history API rather than just React caching.

[koichik]

Opting out is now available. #93633

[arfa123]

How to use it? any guidance?

[koichik]

example from the docs:

'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const { bfcacheId } = useRouter()
  return <form key={bfcacheId}>{/* ... */}</form>
}

[KolbySisk]

I'm seeing: Property 'bfcacheId' does not exist on type 'AppRouterInstance'.ts on the latest version of next (16.2.6)

[r34son]

I'm seeing: Property 'bfcacheId' does not exist on type 'AppRouterInstance'.ts on the latest version of next (16.2.6)

It is not released as a stable, still in canary