Caching and purge

A published page changes only when someone publishes, which makes it ideal to cache. A cache in front of the site — the Maravilla edge, Cloudflare or Fastly — answers repeat visits without asking the site at all, so a page that takes a few hundred milliseconds to render is served in tens of milliseconds.

The catch with any cache is staleness: an author fixes a typo, presses Publish, and visitors keep seeing the old page until the cached copy expires. Studio closes that gap. When a publish completes, it tells the cache to drop what it holds, and the next visitor gets the new page.

How it works

1. The site decides what may be cached. Every response carries a Cache-Control header. A page that says it may be shared is stored; anything else passes through. Nothing is cached unless the site asks for it.
2. The cache serves repeat requests. For as long as the header allows, visitors get the stored copy.
3. Publishing purges the cache. When a publish of the site’s pages finishes, Studio sends a purge to the cache configured on the story. Unpublishing does the same, so a removed page disappears at once.

Purging happens after the publish has completed, never before, so the first visitor after a purge always reads the new content.

Setting it up in Studio

Open the story’s settings and choose the Cache tab.

Maravilla edge: nothing to configure

A site hosted on Maravilla needs no token and no address. Studio purges the address in the story’s Domain field, so check that it is the domain visitors use. The edge cache is enabled per site; ask Maravilla to switch it on for yours.

Cloudflare and Fastly

Paste the zone or service id and the token. The token is stored encrypted the moment you save: it is never shown again, never returned by an API, and never appears in logs. To change it, paste a new one; to remove it, clear the field.

A purge clears everything the zone or service holds. If the zone serves more than this site, all of it is refreshed.

Choosing what to purge

Everything, on every publish is the right choice for almost every site. The navigation, the footer and listings such as “latest news” appear on many pages, so a change to one page usually changes others. Purging everything is the only way to be sure no visitor sees an outdated menu.

Only when selected pages are published is for sites where most publishes do not affect what is cached, for example a site that caches only its news section. You then list rules:

• Purge — publishing a matching page purges the cache.
• Never — publishing a matching page does not, even if a Purge rule matches it. Never always wins.

Pick a page of this site from the list, or type a pattern. Switch on and all pages below it to cover a section. With no Purge rule at all, every page purges except the ones marked Never. The editor shows how many of the site’s pages each rule matches and how many pages in total will purge the cache, so a rule that matches nothing is visible before you save.

Patterns are paths inside the site, starting at /:

Note that this setting decides whether a publish purges, not what is purged: a purge always clears the whole cache.

For developers: what the site must send

The cache stores only what the site marks as shareable. For published pages, send:

Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300

• max-age=0 — browsers always revalidate, so a visitor never holds a stale page.
• s-maxage=60 — the shared cache keeps the page for a minute.
• stale-while-revalidate=300 — after that it serves the stored copy while fetching a fresh one in the background, so no visitor waits for a render.

Because a publish purges the cache, you can raise s-maxage safely; the lifetime then only matters for content that changes without a publish (see below).

Never mark these as shareable:

• Preview and inline-editing requests — anything rendered from the working branch or with an editor session. Send Cache-Control: private, no-store.
• Personal responses — pages that depend on a login, a cookie or the visitor’s traits.
• Form posts, API calls and anything with Set-Cookie.

Content that changes without a publish needs a short lifetime or no caching: a page with time-based variant rules (hasTimeRules, see Personalization), or a block that shows live data such as departures or stock levels. Either cap the page’s s-maxage, or load the live part in the browser so the cached page stays valid.

Checking that it works

Request a page twice and look at the response headers:

curl -sI https://www.example.com/ | grep -iE 'cache-status|age'

The first request is a miss and stores the page; the second is a hit, with an Age header that counts the seconds since it was stored. Publish a page in Studio and request it again: the next response is a miss with the new content, and the ones after it are hits again.

If a page is never a hit, check its Cache-Control header first, then whether the request carries a cookie. If a publish does not refresh the page, check that Purge the cache on publish is on, that the story’s Domain (Maravilla edge) or the id and token (Cloudflare, Fastly) are right, and that your rules include the page you published.