Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 32 ยท Rendering modes

Rendering modes: SSR, SPA, SSG, hybrid

Understand Nuxt universal rendering and hydration, then choose SSR, SPA (ssr: false), static generation or hybrid routeRules like swr and prerender per route.

When someone opens a page of your Nuxt app, who builds the HTML, and when? The answer to that question is the rendering mode, and it decides how fast the page appears, whether search engines can read it, how much your server works, and how fresh the content is. Nuxt supports four answers: build it on the server for each request (SSR), build it in the browser (SPA), build it once ahead of time (static generation), or mix these per route (hybrid).

This lesson explains what each mode does, what hydration is, and how routeRules lets one app use several modes at once. Nuxt configuration and commands are read-only here, because Nuxt cannot run on this site. Two Node stand-ins run live: one produces the three kinds of HTML for the same page, and one resolves route rules for a series of visits using a fake clock. They model the ideas, not the real implementation. Pages and data fetching themselves are covered in File-based routing and Data fetching.

Who builds the HTML?

SSR The server, on every request.
SPA The browser, after JavaScript loads.
SSG The build, once, saved as files.
Hybrid A different answer per route.
1 / 2

Universal rendering and hydration

By default Nuxt uses universal rendering, often just called SSR (server-side rendering). For each request the server runs your Vue components and produces complete HTML. The browser can paint that HTML immediately, and search engines and social-media link previews can read it without running any JavaScript.

HTML alone is not interactive: buttons do nothing yet. So the page also loads your JavaScript, and Vue performs hydration: it walks the HTML that already exists, attaches event listeners and creates reactive state, without throwing the HTML away and rebuilding it. After hydration the page behaves like a normal single-page app: link clicks are handled by the router in the browser, and only data is fetched.

sequenceDiagram
    participant B as Browser
    participant S as Nuxt server
    B->>S: GET /products
    S->>S: Run components, fetch data
    S-->>B: Full HTML + data payload
    B->>B: Paint HTML (fast first view)
    B->>B: Load JS, hydrate (attach listeners)
    B->>S: Later clicks fetch only data

In universal rendering the server sends finished HTML first, and the browser hydrates it.

The server also embeds the data it fetched in the HTML as a payload. During hydration the browser reuses that payload instead of fetching the same data again. That is the reason useFetch and useAsyncData exist and a bare fetch in <script setup> would run twice.

The same page in three forms

The stand-in below renders one tiny product page three ways. The "SPA" version is an empty shell; the "SSR" version contains the product list and an embedded data payload; the "SSG" version is the SSR render performed once at build time and stored as a file. The visible helper strips tags and scripts to approximate what a crawler that does not run JavaScript reads. Real Nuxt output is more elaborate, but the contrast is accurate.

Node.js SPA shell, SSR HTML and a generated file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The output says the SPA shell shows a crawler an empty string, while the SSR page shows Shop Desk lamp: $29 Notebook: $6; the generated file is identical to the SSR output (true), the HTML sizes are 90 bytes versus 306, and the SSR page carries its hydration data. In real life the difference is much larger, because real pages have much more content.

Client-side rendering (SPA)

You can turn server rendering off for the whole app:

TypeScript
// nuxt.config.ts (read-only)
export default defineNuxtConfig({
  ssr: false,
});

The server now sends an almost empty HTML shell, and the browser downloads the JavaScript, runs it and draws everything. This is a single-page application (SPA).

Strengths: the app can be hosted as plain static files, you can use browser-only APIs anywhere, and there is no server rendering cost. Weaknesses: the first view appears later, because nothing shows until JavaScript runs; search engines and link previews see little content; and slow phones suffer most. SPA mode suits private tools behind a login, such as dashboards and admin panels, where SEO is irrelevant.

Static generation (SSG) and prerendering

With static site generation the pages are rendered once, at build time, and saved as HTML files that any static host or CDN can serve:

Terminal
# read-only: run on your machine, not here
npx nuxt generate

nuxt generate renders your pages into .output/public/. Nitro starts at /, follows the links it finds, and prerenders every page it can reach; you can list extra routes (for example from a database) under nitro.prerender.routes. Visitors then get fast, cheap, cacheable HTML, and the pages still hydrate in the browser.

Strengths: the best speed and the lowest hosting cost, with great SEO. Weaknesses: content is only as fresh as the last build, pages that depend on the visitor (a cart, a profile) cannot be fully static, and a site with 100,000 pages takes a long time to build. SSG suits blogs, documentation, marketing sites and landing pages.

Prerendering is the same idea applied to selected routes inside a normal server build. You mark routes in routeRules, shown next.

Hybrid rendering with routeRules

Real sites are rarely one thing. The home page and blog are public and nearly static. The dashboard is private and interactive. A price list changes hourly. routeRules lets you declare a strategy per URL pattern in one place:

TypeScript
// nuxt.config.ts (read-only)
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },          // built once at build time
    '/blog/**': { swr: 60 },           // server-rendered, cached, refreshed after 60 s
    '/pricing': { isr: 3600 },         // like swr, persisted at the CDN on supporting platforms
    '/admin/**': { ssr: false },       // client-only SPA section
    '/account': { cache: false },      // never cached, always fresh
    '/old-page': { redirect: '/new-page' },
    '/api/**': { cors: true },
  },
});

What the main options mean:

  • prerender: true: render at build time and serve the file.
  • swr: seconds (stale-while-revalidate): render on the server, store the result and serve it until it is older than the given time; then serve the old copy once more while a fresh one is built.- isr: similar to swr, but on platforms that support it (for example Vercel and Netlify) the cached page lives at the platform's edge. It needs a host that implements it.
  • ssr: false: skip server rendering for those routes; the browser renders them.
  • cache: server-side cache options (such as maxAge) for finer control, or false for none.
  • redirect, headers, cors: not rendering options, but they use the same pattern syntax.

Patterns use * for one segment and ** for any depth, and when several patterns match one URL their rules are combined, with the more specific pattern taking priority. Exact option names and edge cases can differ between Nuxt versions, so check the current docs when you rely on one.

The second stand-in implements the pattern matching and the SWR timing with a fake clock in seconds, so the output never varies:

Node.js routeRules in action

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the eight lines. The home page is a static file. The first blog visit renders (#1); at t=30 the cached copy is used; at t=70 the copy is older than 60 seconds, so a fresh #2 is built and the visitor is told the stale #1 was available (the stand-in builds synchronously, while the real thing serves the stale copy immediately and refreshes behind the scenes). At t=75 the new copy is served. The admin route gets an empty shell, and /account renders on every request.

Choosing a mode

Decide per route, using a few honest questions:

Question Leans toward
Must search engines or link previews see the content? SSR, SSG or swr
Is the content the same for everyone and rarely changes? SSG / prerender
Does it change often but can be a minute old? swr or isr
Is it personal or behind a login, with no SEO need? ssr: false
Does the answer depend on the cookie of each visitor? SSR with cache: false

A typical shop: / and /about prerendered, /products/** with swr, /cart and /account plain SSR without cache, /admin/** as ssr: false. When in doubt, keep the default (SSR) and add rules only where you can name the benefit.

Two cautions. First, never cache a response that contains one visitor's private data under a shared rule; a cached page is served to everyone. Second, a statically prerendered page is frozen: if it embeds a price, the price is the one from build time until the next build.

Rendering modes also change where code can run. Server rendering executes your component code on the server, where there is no window and no document, and that is the source of the classic hydration mismatch bugs covered next in Hydration and SSR pitfalls. Your deployment target also limits your choice, as Building and deploying explains.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does hydration do?

    After the server sends HTML, Vue hydrates it: it connects to the existing DOM instead of replacing it, making the page interactive.
  2. 2. Which setting turns the whole Nuxt app into a client-side SPA?

    With ssr: false the server sends an empty shell and the browser renders everything. Route rules can also apply ssr: false to selected routes only.
  3. 3. A blog page changes a few times a day and must be readable by search engines. Which route rule fits best?

    swr keeps a server-rendered copy for up to an hour, so crawlers get full HTML quickly and the content still refreshes regularly.
  4. 4. What is the main drawback of fully static generation?

    Static pages are rendered once at build time, so changes appear only after you build and deploy again, unless you combine them with other rules.
  5. 5. Why is it risky to apply a shared cache rule to a page showing the signed-in user's name?

    A cached response is reused for everyone who requests that URL, so personal pages should not be cached under a shared rule.

Summary

  • Universal rendering sends complete HTML from the server, then hydrates it in the browser so it becomes interactive.
  • ssr: false makes an SPA: simple hosting, later first view, weak SEO; good for private tools.
  • Static generation (nuxt generate, prerender: true) builds pages once: fastest and cheapest, but only as fresh as the last build.
  • routeRules mixes modes per URL pattern with prerender, swr, isr, ssr: false and cache.
  • Choose per route based on SEO needs, freshness and whether the page is personal; never share-cache private data.

Next, see what goes wrong when server and browser HTML disagree in Hydration and SSR pitfalls.