On a static site, freshness is simple to reason about even when it is inconvenient: a page changes when you rebuild. Put a server in front and that becomes "a page changes when a cache lets it" — which is better, and is now yours to get right.
There are two caches. Neither knows the other exists.
Your framework has a render cache. The SDK has an in-memory request cache. A request passes through both before it reaches the Delivery API, so the content a visitor sees can be stale in two independent ways, and clearing either one alone looks like it worked.
The SDK cache has no expiry
This is worth stating precisely, because the imprecise version is reassuring and wrong.
The SDK's cache is an LRU bounded by entry count — fifty by default — and nothing else. No TTL. That was a reasonable design for what it was built for: a browser tab is short-lived, so the tab closing was the expiry, and eviction was never the mechanism keeping anything fresh.
A server is not short-lived. One client instance serves every request for the life of the process, and a site with fewer than fifty distinct cache keys never evicts anything at all.
So we published a change and watched:
cached baseline → edit → publish (succeeded)
→ Delivery API: fresh
→ the running app: STILL STALE
The page was not stale for a while. It was stale for good. There is no expiry to wait out, and no amount of reloading gets past it — the app is holding an answer it has no reason to doubt.
The two middle steps are what make that evidence rather than a demonstration. Without confirming the Delivery API had the new content, a stale page could just as easily have meant the publish failed.
The documented fix, which did not work
Our own documentation had an answer for this, and we built exactly what it said: call client.invalidate() on a signal. The natural place for that is a route handler, because a revalidation webhook is a route.
POST /api/revalidate → {"revalidated": true}
→ the running app: STILL STALE
It returned success and changed nothing.
The cause is one we had written down as advice without ever running it. Our docs said one client per process, not per request, and showed a module-level const. The first half is right. The second half does not produce it:
Next evaluates a server component's module graph and a route handler's module graph separately. So lib/content.ts is evaluated twice, and each copy builds its own client with its own cache. We confirmed it the blunt way, by exporting a random id beside the client and reading it from both places in the same running server: lpf90s from the page, zu4ajc from the route handler.
The route was clearing a cache no page was using, and reporting that it had worked.
We had this wrong, and why it survived
That paragraph was in our published documentation. It was written from reading the code, it was plausible, it went through review, and this sample is the first thing that ever executed it.
The reason it survived is worth more than the correction: the failure reports success. A wrong const looks right, works in development — where the process restarts constantly and nothing has time to go stale — and in production returns 200 from a revalidation endpoint forever. There is no error, no log line, and no expiry that eventually hides it. If it had crashed, it would have been fixed the first afternoon.
The general form is the part to take away. "One per process" is a claim about the runtime, not about where you wrote the const. Module identity belongs to the framework, and several of them evaluate one module more than once — per graph, per route segment, per worker, across a hot reload. Any advice shaped like "hold one of these" has to say what makes that true.
What actually works
Pin the instance to something that outlives a module graph. The SDK now ships that, because the six lines are not the hard part — knowing you need them is:
import { createContentClient, sharedContentClient } from '@ebitex/content-sdk'
export const content = sharedContentClient(() =>
process.env.CONTENT_DELIVERY_KEY
? createContentClient({ apiKey: process.env.CONTENT_DELIVERY_KEY, site: process.env.CONTENT_SITE_ID })
: null,
)
With that in place both reads returned the same id and the whole chain worked: publish, revalidate, fresh.
Then the second half, which is just as easy to get half right:
// app/api/revalidate/route.ts
content?.invalidate() // the SDK's cache
revalidatePath('/', 'layout') // the framework's
Both. Clear only the SDK's and the framework may never ask it for anything, so it re-serves its own stored render. Clear only the framework's and it re-renders from content the SDK is still holding. Each one alone produces a route that reports success and leaves a stale page — the same failure mode as before, one layer over.
If you would rather not think about any of this
Two escape hatches, both legitimate:
cache: falseon the SDK client. If you have a CDN in front doing the caching that matters, a second cache underneath it is complexity buying you very little.- A short revalidate window on the framework side, and accept that a publish takes up to that long to appear.
What you should not do is leave the default in place and assume a publish arrives. It does not, and nothing tells you.
Part 4 is what a private key forces you to serve yourself — which turns out to be far less than it first appears.
