BFCache restores and page state

The back/forward cache (BFCache) can keep an eligible document and its execution state in memory for a history navigation. Unlike the HTTP cache, it preserves page state rather than only response data. Eligibility depends on the browser and page state, and an entry can be evicted to reclaim memory. Treat BFCache as an opportunity, not a guarantee of restoration or a fixed speedup.

Metaphorical illustration of a landscape page card, a stack of overlapping pages, and the page appearing again

A metaphor for keeping and restoring a page; it does not depict hidden/frozen states or pagehide/pageshow events.

Which signal confirms a restore?

After a back/forward navigation, pageshow with persisted === true confirms that the saved document was restored. pagehide.persisted === true means the browser intends to preserve the page; it does not promise a later restore. Chromium’s freeze and resume events can also describe background-tab freezing, so use pageshow.persisted when measuring BFCache restores.

What should the application refresh?

Suppose a user leaves a checkout page open, changes the cart elsewhere, and then returns. First check pageshow.persisted to distinguish a restore from a normal load. On a confirmed restore, refresh server-derived details such as price or stock, reopen any connection that may have closed while frozen without creating duplicates, and handle unsaved input according to the application’s policy. This is an illustrative hypothetical, not a test result from a particular application.

A practical eligibility check

  1. Run a real back/forward route in each target browser’s diagnostics and record whether it restored plus any reported exclusion reason.
  2. Do not depend on unload for essential cleanup. Use pagehide where appropriate, and add beforeunload only while unsaved changes need a warning.
  3. Do not treat WebSocket, WebRTC, or IndexedDB as a universal blocker list. Check the reason reported by the actual engine and version. If a connection must be closed before leaving, clean it up on pagehide and restore it on pageshow after a confirmed return.
  4. Do not use Cache-Control: no-store as a BFCache opt-out. Refresh or clear sensitive or time-varying data after a restore instead.

Report actual pageshow.persisted restores and return latency by browser, version, and route; keep them separate from ordinary first-load metrics. One successful route test does not establish a site-wide hit rate.

Sources