Server-Side Rendering (SSR) and Caching
The Laioutr frontend is a Nuxt 3 app with SSR enabled by default and no HTTP caching configured out of the box. The server renders HTML for every request, hydrates on the client, and you opt in to CDN caching by adding route rules.
Caching pipeline overview
Data passes through three caching layers before reaching the user:
| Layer | Where | What it caches | Configured via |
|---|---|---|---|
| Orchestr Entity Cache | Nitro server (in-process) | Query, link, and component resolver results at the entity level | Per-handler strategy, ttl, buildCacheKey (see Orchestr Caching) |
| HTTP / CDN Cache | CDN edge or reverse proxy | Full HTML responses and API JSON responses | Cache-Control headers via routeRules or middleware |
| LRU Client Store | Browser (Pinia-backed) | Entity component data already loaded during the session | Automatic; no configuration needed |
useFetch / useAsyncData caching.Actions and SSR
When you call a server action via useFetchAction, the action runs once on the server during SSR and the result is transferred to the client via the serialized payload. The action does not re-execute on client hydration.
Enabling CDN caching
To have a CDN cache SSR responses, send Cache-Control headers via route rules. A typical starting point:
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
// Default: short CDN TTL for HTML, no browser cache
'/**': {
headers: { 'Cache-Control': 'public, max-age=0, s-maxage=15, must-revalidate' },
},
// Don't cache session-specific pages
'/checkout/**': { headers: { 'Cache-Control': 'private, no-store, no-cache' } },
'/cart': { headers: { 'Cache-Control': 'private, no-store, no-cache' } },
'/login': { headers: { 'Cache-Control': 'private, no-store, no-cache' } },
},
});
nitro.routeRules if you prefer to keep Nitro config separate. The behaviour is identical.TTL guidance:
- HTML — keep TTL short (15-60 seconds) so new deploys propagate quickly and users don't get stale asset references.
- Static assets (JS, CSS, images) — long TTL (1 year) with cache-busting filenames; Nuxt handles this automatically.
Caching API responses
API routes (/api/orchestr/... or your own server routes) can also be cached by the CDN. Add routeRules for those paths with an appropriate Cache-Control header. Do not cache mutation endpoints or routes that return user-specific data.
Overriding from a module
In your module's setup, extend nuxt.options.routeRules to add cache rules for routes your module registers. Merge with existing rules rather than overwriting the whole object so other modules' rules are preserved.
Edge caching on Laioutr Cloud
Laioutr Cloud serves every storefront through Cloudflare's edge, on its assigned hostnames and on a custom domain alike. The edge stores a response only when the response's own headers allow it, and it keeps a separate copy per hostname, path and query string.
| Request or response | What the edge does |
|---|---|
| No cache header | Not stored. Images, fonts and PDFs from public/ are the exception: the edge keeps them for a day. |
s-maxage, or max-age without s-maxage | Stored for that many seconds. |
stale-while-revalidate=<seconds> | After the lifetime ends, the edge serves the stored copy for that many seconds more and refreshes it in the background. This needs a number, and the header must not contain s-maxage or must-revalidate. Otherwise the next visitor waits for the refresh. |
An isr, swr or cache route rule | Stored for the rule's lifetime. See isr rules on Laioutr Cloud and swr and cache rules on Laioutr Cloud. |
private or no-store | Not stored. |
Set-Cookie in the response | Not stored. The cookie reaches the visitor. |
Authorization in the request | The edge neither serves a stored copy nor stores the answer. |
A path under /api/laioutr/ or /api/public/ | Never stored, whatever the header says. |
Vary | See Using Vary headers. |
| Query string | Part of the key, including utm_* parameters and click ids such as gclid. A link with tracking parameters fills a copy of its own, so its first request reaches your storefront. |
| A promotion to production | Clears the edge cache of your production hostnames. |
isr rules on Laioutr Cloud
An isr route rule caches the route at the edge, as it does on Vercel. Nitro does not store the page itself, so the page takes no space in the project's shared cache.
export default defineNuxtConfig({
routeRules: {
'/**': { isr: 3600 },
'/api/**': { isr: false },
},
});
isr value | What the edge does |
|---|---|
Seconds, such as 3600 or { expiration: 3600 } | Serves the stored copy for that many seconds. For 31 days after that, it still serves the stored copy at once and refreshes it in the background. Only a request after those 31 days waits for a new render. |
true, {} or { expiration: false } | Keeps the copy for up to a year. A promotion to production clears it on your production hostnames. |
false or 0 | Nothing. The response's own headers decide, as the table above describes. |
Browsers receive Cache-Control: public, max-age=0, must-revalidate, so they ask the edge again on every visit and always get its current copy. While the edge's copy is within its lifetime, the edge answers that question with 304 Not Modified, and the browser shows the page it already has.
The edge stores responses with status 200, 301, 302, 307, 308, 404 and 410, the same list as Vercel. Under isr: true, a 404 also stays until the next promotion, as it stays until the next deployment on Vercel. The edge does not store a response when:
- the request method is not
GETorHEAD, or the status is not in the list above. A server error is never stored. - the
Cache-Controlcontainsprivate,no-storeorno-cache, as the response to a preview link does. - the handler sets its own
Cache-Control. That header then decides, as the table above describes. ACache-Controlfrom the same route'sheadersrule is not the handler's own, andisrreplaces it. - the request comes from the Studio preview frame.
- the render calls
setResponseCachedDownstream(event, false)to say that it answers one visitor (see Orchestr Caching). - the response sets a cookie, or the request carries
Authorization. - the handler throws an error, for example with
createError.
allowQuery has no effect on Laioutr Cloud, and the build logs a warning for it. The edge keeps a copy per full query string, as the table above describes. The build also warns about an isr value it cannot read, and the edge does not cache that route.
isr rule and an swr or cache rule, isr decides the lifetime, as on Vercel.swr and cache rules on Laioutr Cloud
An swr or cache route rule caches the route at the edge, the same way as isr. Nitro does not store the page, so the page takes no space in the project's shared cache. Code that asks whether a route is cached, such as getRouteRules(event).cache, still sees the rule.
export default defineNuxtConfig({
routeRules: {
'/': { swr: 60 },
'/stores/**': { cache: { maxAge: 300 } },
},
});
| Rule | What the edge does | What the browser receives |
|---|---|---|
swr: 60, or cache: { swr: true, maxAge: 60 } | Serves the stored copy for 60 seconds. For 31 days after that, it still serves the stored copy at once and refreshes it in the background. | public, max-age=0, must-revalidate |
cache: { swr: true, maxAge: 60, staleMaxAge: 300 } | The same, but it refreshes in the background only for 300 seconds after the lifetime. A later request waits for a new render. | public, max-age=0, must-revalidate |
swr: true, or cache: { swr: true } | The same as swr: 1, because Nitro's default maxAge is one second. | public, max-age=0, must-revalidate |
cache: { maxAge: 300 }, without swr | Serves the stored copy for 300 seconds. The next request after that waits for a new render. | max-age=300, the header Nitro itself sends. The browser keeps the page for at most 300 seconds after the edge stored it. |
cache: true, cache: {}, or a value the build cannot read | Nothing, and the build logs a warning. | No header from the rule |
A staleMaxAge of 0 or -1 also gives the full 31 days.
Nitro keeps no copy, so every render that reaches your storefront sees the real request. The market comes from the real hostname, a preview link shows its draft at once and is never stored, the Studio preview frame gets its editor, and every POST runs. The edge stores the same statuses and skips the same responses as for isr, listed above.
Each header in a rule's cache.varies goes into the response's Vary header, except host and x-forwarded-proto, which the edge key already holds. The edge then keeps a copy per value of that header, as Using Vary headers describes.
defineCachedFunction and defineCachedEventHandler in your own server code still store their results in the shared cache. Hashed build files under /_nuxt/ keep their own one-year lifetime under a catch-all rule such as '/**': { swr: 60 }.
Cache-Control: private, or show that part on the client as described in Handling personalized and time-sensitive content. The same holds for isr.Multi-market and locale cache keys
If your frontend serves multiple markets, languages, or domains, the CDN must store separate cached entries for each variant. Without this, a German user could receive HTML cached from a French request.
Laioutr resolves the market and the language from the request's hostname and path prefix, and from nothing else. Laioutr Cloud and Vercel include both in every cache key, so separate markets need no further setup there.
Locale-prefixed routes
When locales are part of the URL path (e.g. /de/products/..., /fr/products/...), the CDN naturally caches them as separate entries since the URL differs. You can still define per-locale route rules:
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
'/de/**': {
headers: { 'Cache-Control': 'public, max-age=0, s-maxage=60, must-revalidate' },
},
'/fr/**': {
headers: { 'Cache-Control': 'public, max-age=0, s-maxage=60, must-revalidate' },
},
},
});
Domain-based multi-market
When each market is served from a different domain (e.g. shop.de, shop.fr), Laioutr Cloud and Vercel keep a separate copy per hostname. Most other CDNs do the same. Verify this with your CDN provider, in particular when one distribution serves several domains: its cache key must include the host.
Using Vary headers
A Vary header makes a CDN keep a separate copy for each value of the request headers it names. Use it only for a header that your render reads, and only when that header has few distinct values. Laioutr's own market resolution reads neither Accept-Language nor a custom header such as X-Market, so a Vary on them only splits the cache.
Vary names | Laioutr Cloud | Vercel |
|---|---|---|
Accept | A copy per exact header value | Part of the cache key by default |
Accept-Encoding | Cached as usual | Part of the cache key by default |
Cookie or * | Not stored | Not stored |
Any other header, such as Accept-Language, User-Agent or X-Market | A copy per exact header value. A request without the header gets its own copy, and de and DE are two copies. | A copy per value |
Each new value fills a copy of its own, so its first request reaches your storefront. A header with many values, such as User-Agent, therefore sends most requests to your storefront. Put such a difference into the URL, or render that part on the client as described in Handling personalized and time-sensitive content.
Server-side caching with swr and cache rules
@laioutr-core/frontend-coreThe rules above only send headers, and a CDN does the caching. Outside Laioutr Cloud, an swr or cache route rule makes Nitro store the rendered page itself, and its keys work differently:
- Nitro renders a cached route with only the request headers listed in
cache.varies, and stores the page under its URL plus those headers. No other header reaches that render: not the cookies, notAccept-Language. @laioutr-core/frontend-coreaddshostandx-forwarded-prototovarieson every caching rule. Each market domain therefore gets its own stored page, anduseRequestURL()keeps thehttpsscheme behind a proxy.- If your render reads another header, list it yourself. The
swrshorthand cannot carryvaries, so write the rule as acacheobject. - A preview link's render is stored too, under its own URL. See Content preview.
- Send the same header in
Varyas well. The rule'sCache-Controllets a CDN store the page too, and withoutVarythe CDN keeps one copy for every value.
export default defineNuxtConfig({
routeRules: {
'/': {
cache: { swr: true, maxAge: 60, varies: ['accept-language'] },
headers: { Vary: 'Accept-Language' },
},
},
});
Every listed header becomes part of the key, so the cardinality warning above applies here as well: never list cookie or any other header that differs per visitor.
On Laioutr Cloud, Nitro stores nothing for these rules and the render sees every request header. The headers in varies go into Vary for you, and the same cardinality warning applies to the edge's copies. See swr and cache rules on Laioutr Cloud.
Stored 404 page
@laioutr-core/frontend-coreA scanner or a crawler can request hundreds of paths that no route knows, and each one costs a full render of the 404 page. The storefront therefore keeps the 404 page that it rendered for such a path, and answers the next unknown paths from that copy. From @laioutr-core/frontend-core 0.83.0 this is on by default. Before 0.83.0, a project turns it on with "cachedNotFoundPage": true.
- Each server instance keeps its own copy in memory, one per domain and language of the project, for 10 minutes. After that, the next unknown path renders the 404 page again.
- Only a path that matches no route takes part. A product or a category that no longer exists still renders its 404 page at its own URL.
- Only a
GETorHEADrequest that accepts HTML and carries noCookieand noAuthorizationheader takes part. A preview link never does. - A request with a query string gets the stored copy, but its own render is never stored.
- A render is not stored when it sets a cookie, sends
Cache-Controlwithprivateorno-store, or callssetResponseCachedDownstream(event, false)(see Orchestr Caching). - The response header
x-laioutr-404ishitwhen the answer came from the copy, andmisswhen the render fills a copy.
Turn it off when your 404 page differs per request: a page variant chosen per visitor through the select-page-variant hook, or content chosen by request headers. With the stored page, every visitor gets the version that one request rendered, for up to 10 minutes. A change to the 404 page that you publish in Studio also shows only after that time.
{
"config": {
"cachedNotFoundPage": false
}
}
The storefront reads the project file at build time, so the change applies with the next deployment. The environment variable NUXT_LAIOUTR_CACHED_NOT_FOUND_PAGE (true or false) overrides the file for one deployment. Under nuxt dev the stored page is off unless the project file sets it to true, so an edit to the 404 page shows at once.
Handling personalized and time-sensitive content
For CDN caching to work, the SSR HTML for a given URL (and locale/market) must be the same for every user. Move personalized or session-specific content to the client:
- Wrap personalized UI (cart count, wishlist, "Hello, {name}") in
<ClientOnly>or guard it withimport.meta.client/onMounted. - Show a skeleton placeholder with matching dimensions to avoid layout shift.
- For time-sensitive data (stock levels, live prices), either shorten the TTL for those routes or fetch the data client-side after hydration so the cached HTML stays stable.
LRU client-side store
The third caching layer lives in the browser. When Orchestr returns entity data during a page load, resolved entity components are stored in a Pinia-backed LRU cache.
How it works
Consider a typical shopping flow. You browse a product listing page where each product card loads entity components (title, image, price). When you click through to a product detail page, the LRU store already has those components cached. They render immediately while the PDP fetches remaining components (description, stock, reviews).
Key characteristics:
- Automatic — no configuration needed.
- Entity-component granularity — cache key is entity identifier + component type. Pages sharing the same entity share cached data.
- Session-scoped — lives in browser memory, not persisted to storage.
- LRU eviction — bounded memory; least recently used entries are evicted first.
product-title, product-image) across listing and detail pages to maximize cache hits.Entry script loading
The first page view downloads the storefront's JavaScript bundle and, by Nuxt's default, a set of
prefetch and modulepreload hints for the chunks around it. On a slow mobile connection those
hints compete with the hero image before the first paint. The entryScript block in the config
section of your project's laioutrrc.json controls both. Without it, the entry script stays where
Nuxt puts it and only the prefetch links and the entry's own preload leave the head. A faster first
paint is the opt-in below:
{
"config": {
"entryScript": {
"loading": "after-paint",
"hints": "siblings"
}
}
}
| Setting | Values | Default | Effect |
|---|---|---|---|
loading | eager, after-paint | eager | eager keeps the entry script in the head. after-paint removes it and requests it from a small inline script after the window load event, so its bytes stop competing with the largest image. |
hints | all, siblings, with-entry, none | siblings | siblings drops the prefetch links and the entry's own preload but keeps the preloads for the chunks the entry imports, so those are still discovered while the page parses and interactivity does not move. with-entry (frontend-core 0.66.1 and later, only with loading: "after-paint") takes those preloads out of the head too, and the inline script requests them together with the entry, so they stop competing with the first paint and are still in flight before the entry needs them. Under eager it acts as siblings. none drops every hint, so the imported chunks also stop competing with the first paint, but interactivity comes around a second later on a slow connection, because the entry then discovers those chunks itself. all keeps Nuxt's output. |
Measured on the reference storefront's homepage under mobile throttling, against Nuxt's own head:
loading: "after-paint" took the largest contentful paint from 4,018 to 3,226 ms with Time to
Interactive unchanged. hints: "none" with the script eager took 900 ms off the largest
contentful paint and added about 1.2 s to Time to Interactive.
With loading: "after-paint", hints: "with-entry" measured on another storefront's homepage made
the first paint about 0.6 s earlier than siblings, and Vue hydrated at the same time. That holds
while the imported chunks are smaller than the entry, because they now download alongside it. A
project whose imported chunks outweigh its entry should measure before it switches.
The setting applies to production builds only. To restore Nuxt's own head without changing the
project file, set both environment variables NUXT_PUBLIC_LAIOUTR_ENTRY_SCRIPT_LOADING=eager and
NUXT_PUBLIC_LAIOUTR_ENTRY_SCRIPT_HINTS=all on the deployment. The resolved value is on the public
runtime config as useRuntimeConfig().public.laioutr.entryScript.
Render config prefetching
Resting on or tabbing to a <NuxtLink> loads the target page's render config into the Nuxt payload. Opening that page then costs no request for the config at all, on a first visit as much as on a return.
The config is cacheable in its own right: its URL carries a hash of the project configuration, so both the CDN and the browser keep the response until an edit changes that hash.
frontend-core:link:intent fires on the same signal, so an app can warm its own work for the page a visitor is heading to. See Hooks.
Quick reference
| What | Where | Default |
|---|---|---|
| SSR | nuxt.config.ts → ssr | true (Nuxt default) |
| HTML caching | routeRules → headers['Cache-Control'] | Not set |
| API response caching | routeRules for /api/** or per-handler headers | Not set |
| Multi-market cache keys | Hostname or URL-based locale prefix | Built in: hostname and path |
| Orchestr data cache | Per-handler strategy, ttl, buildCacheKey | See Orchestr Caching |
| Stored 404 page | laioutrrc.json → config.cachedNotFoundPage | On from frontend-core 0.83.0, off under nuxt dev |
| Client store | Automatic LRU | Always on |
Routing
How Laioutr generates routes from page types, how URL patterns are configured, and how markets affect route resolution.
Tracking
Laioutr’s analytics layer gives you one typed API to emit events. Destinations declare the consent purposes they need, and the bus delivers each event only to the destinations the visitor has allowed.