SSR strategies

rune caches the HTML it renders for static SSR routes. The strategy controls when a route's HTML is put into that cache. There are three: eager, background, and lazy. You set a default on createApp and can override per route.

The three strategies

eager (default)

All eager SSR routes are rendered into the cache at server start, before it begins accepting traffic for them. The very first visitor gets a cache hit.

SSR cache: 48 pages rendered (eager)
EkkoJS SSR listening on http://0.0.0.0:3000

• Pros: every page is warm instantly; first request is fast.
• Cons: startup does the work for all pages (slower boot if you have thousands of pages).
• Use for: content and marketing sites, docs, anything with a bounded page count where you want a warm

cache from the first request. This is the right default for most apps.

background

The server starts listening immediately, then renders background routes into the cache just after start (asynchronously). Early requests to a not-yet-warm route render on demand; once the background pass completes, all are cached.

• Pros: fast boot; the cache fills without blocking startup.
• Cons: a brief window after boot where some pages render on first hit.
• Use for: large sites where eager boot would be too slow, but you still want everything cached soon.

lazy

The route is not pre-rendered. Its HTML is produced on the first request and cached from then on (subject to ttl). Subsequent requests are cache hits.

• Pros: zero startup cost; only pages that are actually visited are rendered.
• Cons: the first visitor to each page pays the render cost.
• Use for: long-tail pages, rarely-visited routes, or when boot time matters more than first-hit latency.

How strategy interacts with route kind

Strategies apply to static routes that have an ssr(), those are the cacheable ones. Dynamic routes (:param, *catch) always serve a shell and render on the client regardless of strategy (their content is per-URL, so there is nothing universal to cache). A static route without ssr() also serves a shell.

Per-route overrides

Mix strategies to fit each page:

Choosing a default

• Small/medium content site or docs → eager (warm everything at boot).
• Hundreds/thousands of pages → background (boot fast, warm shortly after) or lazy (warm on

demand).

• Mostly dynamic/personalised → strategy matters less; those routes are shells anyway.

What "cached" means here

The cache stores the assembled HTML document keyed by path, with an optional ttl (seconds) and tags. A cache hit serves the stored HTML directly (with a tiny patch to inject the current __user if any). When the cache is stale or absent, the route re-renders. You control invalidation explicitly, see Caching & invalidation.

Next: the client side of the handoff, Hydration.