Skip to main content

Cacheable public pages

Render public pages without the session so a CDN or ISR cache can share the HTML.

With authentication on, the server reads the session cookie on every page, exchanges it for a Convex session token, and renders the page for that user. The response gets Vary: Cookie, and a response for a signed-in user gets Cache-Control: private, no-store. A shared cache, such as Vercel ISR or a CDN, must not store such a page.

Turn off session resolution during server rendering for pages that look the same for every visitor. The server then renders these pages as an anonymous visitor:

  • It ignores the session cookie and does not call the token exchange.
  • It adds no Vary: Cookie and no private cache header.
  • useConvexAuth() reports anonymous during server rendering.
  • Queries with auth: 'optional' run anonymously. Queries with auth: 'required' do not run on the server.

The browser reads the session after hydration, as for any other page.

Turn it off for some routes

Set the convex.ssrAuth route rule:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
  convex: {
    auth: { origin: process.env.SITE_URL },
  },
  routeRules: {
    '/api/**': { isr: false, cache: false },
    '/admin/**': { isr: false, convex: { ssrAuth: true } },
    '/**': { isr: 86400, convex: { ssrAuth: false } },
  },
})

The rule '/**' also matches /api/**, which includes the sign-in routes under /api/auth. A cache must never store a response from these routes, because it could serve the session of one user to another visitor. List only your public page paths, not '/**'. The /api/** rule is a second guard that turns caching off for the auth routes.

On Nuxt 5, a cached route (cache, swr, isr) ignores the query string unless the rule sets allowQuery. On Nuxt 4, the cache key includes the query string. On both, do not cache a page whose HTML depends on a query, such as ?redirect=.

A cache rule (cache, swr, isr) stores the rendered page and replaces the Vary: Cookie and Cache-Control: private, no-store headers that the module sets on pages for signed-in users. This is true on Nuxt 4 and Nuxt 5. On Nuxt 4, the cached render also runs without the request cookies, so SSR auth renders those pages signed out. On Nuxt 5, a routeRules headers rule or a server middleware that sets cache headers also overrides the module's headers; on Nuxt 4 the module's headers win over these. Set convex: { ssrAuth: false } on every cached route, or remove the cache rule.

The module checks the routeRules and nitro.routeRules of your nuxt.config at build time. It does not check server middleware, defineRouteRules() in page files, or rules that other modules add. For each of those checked rules that caches a page with SSR auth on, it logs this warning (here for '/blog/**': { swr: 3600 }):

Route rules "/blog/**" cache pages that resolve the Convex session during SSR. A cache rule replaces the `Vary: Cookie` and `Cache-Control: private, no-store` headers the module sets on signed-in pages, and on Nuxt 5 a `headers` rule with cache headers does too. Set `convex: { ssrAuth: false }` on cached routes or drop the cache rule.

Check server middleware, page-level rules and rules from other modules that set cache headers yourself. A cache-control header that forbids storing (no-store, private, no-cache, max-age=0) is not a cache rule and gets no warning.

Turn it off for all routes

Set auth.ssr: false. A route rule with convex: { ssrAuth: true } turns it on again for matching routes.

nuxt.config.ts
export default defineNuxtConfig({
  convex: {
    auth: { origin: process.env.SITE_URL, ssr: false },
  },
  routeRules: {
    '/account/**': { convex: { ssrAuth: true } },
  },
})

Protected pages

The server does not know the visitor on these routes, so the route middleware does not redirect during server rendering. The browser applies convexAuth after the session loads. Keep SSR auth on for protected pages when the server must redirect before it sends HTML.

Show user-specific parts

Render parts that depend on the user in the browser only, for example with <ClientOnly>, or after await useConvexAuth().ready(). The server HTML must not contain them, because every visitor gets the same HTML.

Combine this with client.connect: 'on-demand' to keep the Convex and Better Auth clients off these pages as well.