Route Caching rules

[pi0]

Server Rendering Strategies

Generally, we have several possible ways to render a route. In the table below, a summary is added. There are some similarities between these methods and to avoid confusing users for choosing the proper platform, we need a unified way of describing them and mentioning which nuxt version supports which and what are the trade-offs.

Strategy	Known As	Shared Cache (1)
Server-Side rendering	SSR	❌
Client-Side rendering	SPA	❌
Preview	Preview	❌
Prerendering (2)	Generate, Static	✔️
Crawling (2)	Full Static	✔️
HTTP caching	SWR, HTTP Cache	✔️
On-demand pre-rendering (2)	Netlify Builder, Vercel ISR	✔️

• (1) With a Shared cache, we can respond regardless of user requests (Auth Headers, Cookies, IP, Browser) which makes responding faster with caching possibilities but is not always desired
• (2) [on-demand] prerendering and crawling are simply edge-based permanent caching strategies that invalidate on each CI build
• For strategies with Shared Cache we need to disallow specific functionalities like access to query params during development

Strategy Configuration

We need a schema to describe route/route-groups in nuxt.config with their desired rendering strategy. In addition to caching, it can be useful to describe other meta like redirect rules and password protection. One important note is that, this configuration needs to be serializable to be reusable for vendor-specific purposes.

Example:

export default defineNuxtConfig({
  routes: {
    '/': { prerender: true }, // Once per build (via builder)
    '/blog/*': { static: true }, // Once on-demand per build (via lambda)
    '/stats/*': { swr: '10 min' }, // Once on-demand each 10 minutes (via lambda)
    '/admin/*': { ssr: false }, // Client-Side rendered
    '/react/*': { redirect: '/vue' }, // Redirect Rules
  }
})

Depending on the nitro platform or in-development, we can map route configuration to proper implementation.

For the context, with nuxt2, we have these options:

• mode / ssr: Switch on/off SSR for entire project
• generate.routes (helping crawler and prerenderer)
• req.spa (see Runtime Strategies)
• static: Enable Prerender/Crawler for all routes

New routes can cover all but we can preserve them as shortcuts and compatibility

Runtime Strategies

Runtime strategies might be also possible but not working for all platforms if they need declarative configuration (like Vercel) and reduce optimization possibilities since we cannot easily predict what will happen for a specific route or if it is a request based rule or not. Yet we can partially support them for special cases (like this). Also we can have a way to infer config from pages.

Client-Side Behavior

Client Rendering behavior also depends on server Strategies:

• For client-side rendering (CSR and SPA), we need to apply server logic before hydration
• For Preview mode, we need to override server response (if any) and apply server-logic
• For the crawling method, we need to fetch payload instead of normal logic
• For SWR method, we need to revalidate Etag and reload if a mismatch happening
• For Shared Cache methods (except Crawling), we need to ensure if there is any newer API response, gracefully handling errors.

[pi0]

Related vercel/next.js#28180. We might also set UA-based rules to enable ISR/Static based on user-agent only for mobile or search engines with a simple API. (but it obviously is not supported on all edge CDNS and need a nitro hit at least once also they cannot benefit shared-cache)