/nuxt

Rendering Modes

Nuxt supports multiple rendering modes: universal (SSR), client-side (CSR), and hybrid rendering.

Universal Rendering (Default)

Server renders HTML, then hydrates on client:

// nuxt.config.ts - this is the default
export default defineNuxtConfig({
  ssr: true,
})

Benefits:

• Fast initial page load (HTML is ready)
• SEO-friendly (content is in HTML)
• Works without JavaScript initially

How it works:

1. Server executes Vue code, generates HTML
2. Browser displays HTML immediately
3. JavaScript loads and hydrates the page
4. Page becomes fully interactive

Client-Side Rendering

Render entirely in the browser:

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false,
})

Benefits:

• Simpler development (no SSR constraints)
• Cheaper hosting (static files only)
• Works offline

Use cases:

• Admin dashboards
• SaaS applications
• Apps behind authentication

SPA Loading Template

Provide loading UI while app hydrates:

<!-- app/spa-loading-template.html -->
<div class="loading">
  <div class="spinner"></div>
  <p>Loading...</p>
</div>

<style>
.loading {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100vh;
}
.spinner {
  width: 40px;
  height: 40px;
  border: 4px solid #f3f3f3;
  border-top: 4px solid #00dc82;
  border-radius: 50%;
  animation: spin 1s linear infinite;
}
@keyframes spin {
  to { transform: rotate(360deg); }
}
</style>

Hybrid Rendering

Mix rendering modes per route using route rules:

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // Static pages - prerendered at build
    '/': { prerender: true },
    '/about': { prerender: true },

    // ISR - regenerate in background
    '/blog/**': { isr: 3600 }, // Cache for 1 hour
    '/products/**': { swr: true }, // Stale-while-revalidate

    // Client-only rendering
    '/admin/**': { ssr: false },
    '/dashboard/**': { ssr: false },

    // Server-rendered (default)
    '/api/**': { cors: true },
  },
})

Route Rules Reference

Nitro v3 changes:

• Redirect rules use status (not statusCode): redirect: { to: '/new', status: 302 }.
• Cached routes (cache/swr/isr) now key on path only — the query string is dropped. Keep it with allowQuery: true or a list of param names: cache: { swr: true, maxAge: 60, allowQuery: ['page'] }.

Inline Route Rules

Define per-page:

<script setup lang="ts">
defineRouteRules({
  prerender: true,
})
</script>

Prerendering

Generate static HTML at build time:

// nuxt.config.ts
export default defineNuxtConfig({
  // Prerender specific routes
  routeRules: {
    '/': { prerender: true },
    '/about': { prerender: true },
    '/posts/*': { prerender: true },
  },
})

Or use nuxt generate:

nuxt generate

Nuxt 5: Payload Extraction & Error Pages

• Payload extraction defaults to 'client' (experimental.payloadExtraction): the payload of a prerendered/cached page is inlined in the HTML for the initial render, and _payload.json is only fetched during client-side navigation. Forced to false when ssr: false.
• nuxt generate / nuxt build --prerender emit SPA fallbacks into .output/public/: 200.html (client router handles unmatched paths) and 404.html (keep 404 status + load app). A plain nuxt build does not.
• Prerender the error page with experimental.prerenderErrorPages: true — Nuxt renders error.vue at build time into 404.html. Because one file serves every missing path, guard request-specific data with import.meta.prerender and wrap request-specific markup in <ClientOnly>.

Programmatic Prerendering

// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    'prerender:routes'({ routes }) {
      // Add dynamic routes
      const posts = await fetchPostSlugs()
      for (const slug of posts) {
        routes.add(`/posts/${slug}`)
      }
    },
  },
})

Or in pages:

// server/api/posts.ts or a plugin
prerenderRoutes(['/posts/1', '/posts/2', '/posts/3'])

Edge-Side Rendering

Render at CDN edge servers:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages', // or 'vercel-edge', 'netlify-edge'
  },
})

Supported platforms:

• Cloudflare Pages/Workers
• Vercel Edge Functions
• Netlify Edge Functions

Conditional Rendering

Use import.meta.server and import.meta.client:

<script setup>
if (import.meta.server) {
  // Server-only code
  console.log('Running on server')
}

if (import.meta.client) {
  // Client-only code
  console.log('Running in browser')
}
</script>

For components:

<template>
  <ClientOnly>
    <BrowserOnlyComponent />
    <template #fallback>
      <p>Loading...</p>
    </template>
  </ClientOnly>
</template>