App router caching pitfalls

The framework caches at four levels and each one is invisible until it bites. Here is the order I now check them in when something is stale.

The four layers

• The request memo, which lives for one render pass
• The data cache, which survives deployments unless you say otherwise
• The route cache, which is why your dynamic page rendered once
• The client router cache, which is why it is still wrong after a hard refresh

Nearly every bug I have chased was the third one. A route that reads no dynamic input gets rendered at build time, and it does not tell you.

The diagnostic

Add a timestamp to the page. If it never changes, you are static. If it changes on reload but not on navigation, you are hitting the client cache. Two minutes of instrumentation beats an hour of documentation.

A debugging order that works

Instrument before you read documentation. Put the current time in the page, deploy, and observe. Whether the timestamp changes, and under which kind of navigation, identifies the layer in about two minutes.

The one that catches everyone

A page with no dynamic input renders once at build time and serves that forever. It is correct behaviour and it is invisible, because nothing warns you that your page was eligible. If your data is fresh in development and stale in production, this is almost always why.