Caching

Two caches hold rendered output, and both are invalidated by content changes without any code of yours:

• The page cache keeps whole public pages for anonymous visitors, serving a stale copy while one background render replaces it. It is off until engine.yaml turns it on.
• The {% cache %} tag keeps one region of a template, keyed by what you name and registered against every document it read, so publishing one of them clears it.

Static files, built assets and image derivatives are cached by the browser and any CDN through their headers (Frontend build, Images).

The page cacheCopy Anchor Link

# config/engine.yaml
cache:
  pages:
    enabled: true
    fresh: 60s
    stale: 24h
    max_memory: 256MB
    concurrency: 2
    warm:
      paths: ["/"]
      top: 50
      deadline: 60s

The cache is per process. A publish, unpublish, trash, navigation change or tag change on any replica moves every replica’s cache generation within one invalidation poll (cache.invalidation_poll, 2 seconds by default); every page stored before is then stale, and pages read in the last 15 minutes are re-rendered in the background without waiting for a visitor. A body over 4 MB is not stored.

Responses carry X-Cache: hit, stale or miss.

Which pages are cachedCopy Anchor Link

A request is answered from the cache, and its response stored, only when all of these hold:

• It is a GET or HEAD for a whole page: not a fragment or sigmx request, not a preview (?preview, ?token), not the profiler (?_profile), with no Authorization header.
• No staff member and no member is signed in.
• The response is 200, 404, 410, 301 or 308, is HTML, sets no cookie, has no Cache-Control saying private or no-store, and varies on nothing but Accept-Encoding.
• The render printed nothing that belongs to one request.

The cache key is the host and the full address with its query string, so each page of results and each filtered list is a page of its own.

What a template does that stops a page being storedCopy Anchor Link

Keep them out of pages that should be fast for everyone: a site-wide newsletter form works for anonymous visitors without breaking the cache, because its token is empty for them.

The cache tagCopy Anchor Link

{% cache 'news-card' key=article.id version=article.updatedAt ttl='1h' %}
  {% component 'teaser' doc=article %}
{% endcache %}

{% cache 'latest-news' ttl='10m' %}
  {% for a in query('article').orderBy('publishedAt', 'desc').limit(6).all() %}
    {% component 'teaser' doc=a %}
  {% endfor %}
{% endcache %}

{% cache 'results' vary=['query'] %}
  {% for item in items %}{% component 'teaser' doc=item %}{% endfor %}
{% endcache %}

{% cache 'name' key=... version=... ttl='...' vary=[...] %}...{% endcache %}

Every option is optional and written at most once.

What is always in the keyCopy Anchor Link

You cannot get these wrong, because the engine adds them: the site, the locale, the formatting locale, the template file and the line the block starts on (two blocks that share a name never collide), the route the page was served by, the block’s name, and the key, version and vary values. vary=['locale'] is accepted and adds nothing.

A block’s life, from the first render to the publish that clears it:

flowchart TD
  R["Render reaches cache block"] --> P{"A public page<br/>for a visitor?"}
  P -- no --> BODY["Render the body, store nothing"]
  P -- yes --> K["Key: site, locale, file, line,<br/>route, name, key, version, vary"]
  K --> H{"Stored and<br/>not invalidated?"}
  H -- hit --> OUT["Print the stored output"]
  H -- miss --> RB["Render the body"]
  RB --> PR{"Printed per-request output?<br/>token, member, focus, preload"}
  PR -- yes --> NS["Print it, do not store"]
  PR -- no --> ST["Store it against the documents<br/>and lists it read"]
  ST -.->|"a publish of one of them"| H

When a block is usedCopy Anchor Link

Only in a public page rendered for a visitor: an entry, an index, a landing page, search and the error pages. A preview, a fragment request, the admin, the member portal and mail render the body every time, so a draft or one member’s view is never stored. Outside those pages the tag simply renders its body.

InvalidationCopy Anchor Link

A stored block is registered against cache scopes found by the render, not written by you, and is a miss once any of them changes:

The scopes come from the variables the body names (including {% set %} inside the block), followed four levels deep. A body that includes another template sees the whole context, so every document in it is registered; a component sees only its props. A block nested in another passes its scopes up.

A change the engine cannot see, such as an organisation’s details shown on a listing or an asset’s alt text, is bounded only by the block’s ttl. Set a ttl that is acceptable for those.

A block that read a document while a publish of it was in flight is not stored, so a block is never stamped with a revision it did not read.

What is never storedCopy Anchor Link

A block whose render printed a CSRF token, read or required the signed-in member, emitted {% announce %} or {% focus %}, added an image preload (priority=true) or a video, is rendered and not stored. In development the engine logs which block and why.

engine-dmo check reports the obvious cases from the source as errors: csrfInput, csrfToken, csrf, now, enquiryForm, subscribeForm and {% requireMember %} inside a cache block.

_shared/article/index.html:12:1: error: cache block bad holds csrfInput, which emits per-request output: csrfInput() prints this visitor's CSRF token
      = move it outside the {% cache %} block, or leave the block uncached

It also refuses, at parse, a name that breaks the naming rule, a ttl over seven days or that is not a duration, an unknown vary value, and an unknown option.

Choosing what to cacheCopy Anchor Link

• Cache regions that run queries: a query() strip, a smart list, a facet panel, a card grid. A single field print is not worth a block.
• Give the block a key that names what makes it differ (the document’s id for a card), and a version that changes when it should be rebuilt (updatedAt).
• Leave forms, the signed-in member and the current time outside the block.
• Prefer the page cache for whole pages. Blocks help most on pages the page cache cannot keep: pages for signed-in members, and pages with query strings that vary widely.

Seeing it workCopy Anchor Link

• The admin’s cache screen shows, per block name, the hit rate, entries, size, age, scopes and the last invalidation, and purges by block name, route, document or site.
• Under engine-dmo serve --dev, the profiler (open a page with ?_profile) shows each block’s hit, miss or skip with the reason.
• In development (serve --dev) and with template.cache: false in engine.yaml, templates are parsed afresh on every render, so an edited template counts at once. In production, templates are compiled at boot and a template added or removed counts from the next restart.
• engine-dmo warm requests each site’s warm paths, indexes and most visited pages from a running release after a deploy, and reports whether the page cache answered each and how long it took.

RelatedCopy Anchor Link

• Configuration reference: engine.yaml: cache.*.
• Forms in templates: tokens and anonymous visitors.