Skip to content

Page cache

Ekit keeps the rendered HTML of your site's pages for a short time. A cached page is served without querying your data, without rendering the templates and without calling Methods, so it returns in well under a millisecond on the server.

There is nothing to configure: every page is cached for 300 seconds by default.

Changes are visible immediately

The cache is cleared automatically — you never wait for the lifetime to run out after a change made in Ekit:

Change Pages cleared
A site file (view, partial, layout, CSS, JS, image, i18n) is saved, uploaded, renamed or deleted All pages of that site
A Method or a Secret is created, updated or deleted All pages of that site
An AI generation writes files, a backup is restored All pages of that site
An entry, a table, a field, a slug, a translation or the project settings change All pages of every site of the project

The lifetime only matters for what Ekit cannot see change: data returned by Methods (external APIs).

Lifetime: cache.ttlSeconds

Set the lifetime of a page in its front matter, in seconds:

---
cache:
  ttlSeconds: 60     # this page is rendered again at most once a minute
---
Value Effect
(absent) 300 seconds.
60, 3600… That many seconds (maximum 86400, one day).
0 The page is never cached: rendered on every view.

The lifetime sets the freshness of Method data

A page that uses a type: method datasource calls the Method once per lifetime (and per distinct URL), not on every view. With the default, the data of the external API can be up to 5 minutes old.

  • Prices, stock, availability: use a short lifetime (30, 60).
  • Content that changes rarely: a longer lifetime reduces the calls to paid APIs.
  • Data that must be exact on every view: ttlSeconds: 0 — every view then calls the Method.

Calls made from the browser with ekit.methods.call() are never cached.

What is cached

A page is cached per URL: language, page, slug and query parameters (?page=2, ?q=…, ?cursor=…). The order of the parameters does not matter.

Not taken into account (the page is shared): tracking parameters — utm_*, fbclid, gclid, msclkid, _ga, _gl, mc_cid, mc_eid and similar.

Never cached:

  • a page whose rendering has an error, or whose Method datasource failed (the next view tries again);
  • a page whose single entry is not found (unknown slug);
  • a page larger than 2 MB;
  • a URL with more than 10 parameters or longer than 512 characters of parameters;
  • the Studio preview, which always shows the current state of your files and data.

Adding ?preview=1 or ?format=json to a public URL has no effect: only the Studio can open an uncached preview.

Browser revalidation

On top of the server cache, every public page is sent with an ETag and Cache-Control: no-cache. The browser (or CDN) keeps the page and asks on each visit whether it changed; when it did not, the server answers 304 Not Modified without resending the HTML.

Checking the cache

Response headers of a public page:

Header Meaning
X-Ekit-Cache: HIT Served from the cache.
X-Ekit-Cache: MISS Rendered now, then cached.
X-Ekit-Cache: BYPASS Rendered now, not cached — the reason is in X-Ekit-Cache-Skip (ttl-0, render-errors, too-large, query-limits, preview…).
Server-Timing Server time spent on the page (cache;dur=… or render;dur=…, in ms). 
curl -sI https://www.example.com/en/ | grep -i -E 'x-ekit-cache|server-timing|etag'