Nuxt 3 SSG Deployment auf Static Hosts: Netlify, Vercel, Cloudflare

1. Warum Static Site Generation für Nuxt 3

Static Site Generation in Nuxt 3 bedeutet, dass jede Seite der Anwendung zur Build Zeit vollständig als HTML Datei erzeugt wird, statt bei jedem Request erneut auf einem Server gerendert zu werden. Das Ergebnis ist ein Verzeichnis reiner statischer Dateien, das sich auf jeden beliebigen Webserver oder Static Host kopieren lässt, ganz ohne Node.js Laufzeitumgebung im Produktionsbetrieb. Für Marketingseiten, Dokumentation und Blogs mit überschaubarer Änderungsfrequenz ist das häufig die robusteste und günstigste Deployment Option.

Der entscheidende Vorteil von Static Site Generation gegenüber Server Side Rendering liegt in der Betriebssicherheit: Eine statische Datei kann nicht abstürzen, hat keine Serverless Cold Starts und skaliert automatisch über ein Content Delivery Network, ohne dass eine Anwendungslogik pro Request ausgeführt werden muss. Genau diese Eigenschaft macht statische Nuxt 3 Builds zur bevorzugten Wahl für Projekte, bei denen Ausfallsicherheit und niedrige Latenz wichtiger sind als Echtzeit Personalisierung.

Ein praktisches Beispiel verdeutlicht den Unterschied: Eine Firmenwebsite mit fünfzig Unterseiten, die sich einmal pro Woche redaktionell ändert, profitiert kaum von Server Side Rendering bei jedem Aufruf. Mit Nuxt 3 und Static Site Generation wird der komplette Seitenbaum einmal beim Build generiert und danach über ein Edge Netzwerk ausgeliefert, wodurch jede Anfrage direkt vom nächstgelegenen Edge Knoten beantwortet wird, ohne Rechenlast auf einem Origin Server.

2. nuxt generate im Detail verstehen

Der Befehl nuxt generate ist der zentrale Baustein für Static Site Generation in Nuxt 3. Intern startet er zunächst einen Build im Hintergrund, crawlt anschließend alle über Links erreichbaren Routen der Anwendung und rendert jede gefundene Route zu einer eigenständigen HTML Datei im Ausgabeverzeichnis .output/public/. Dieser Crawler folgt automatisch jedem <NuxtLink> in der Anwendung, wodurch in den meisten Fällen keine manuelle Routenliste gepflegt werden muss.

Wichtig für Static Site Generation ist der Unterschied zwischen nuxt build und nuxt generate: nuxt build erzeugt einen Nitro Server, der zur Laufzeit rendert, während nuxt generate zusätzlich den kompletten Crawling und Prerendering Schritt ausführt. Am Ende von nuxt generate liegt ein rein statisches Verzeichnis vor, das ohne jede Node.js Ausführung funktioniert. Für Projekte mit ausschließlich statischen Anforderungen ist nuxt generate daher der richtige Befehl in der CI Pipeline, nicht nuxt build.

# Standard command for full static site generation
npx nuxt generate

# Resulting output structure — pure static files, no Node.js needed
.output/
└── public/
    ├── index.html
    ├── about/
    │   └── index.html
    ├── blog/
    │   ├── index.html
    │   └── my-first-post/
    │       └── index.html
    └── _nuxt/
        └── [hashed assets]

# Preview the generated static build locally
npx serve .output/public

3. Dynamische Routen für das Prerendering entdecken

Der automatische Crawler von Static Site Generation in Nuxt 3 findet nur Routen, die tatsächlich über <NuxtLink> Elemente verlinkt sind. Dynamische Routen wie /blog/[slug].vue, deren konkrete Werte aus einer API oder einem Content Modul kommen, werden vom Crawler nicht automatisch erraten. Für diesen Fall muss die Nuxt Konfiguration explizit mitgeteilt bekommen, welche konkreten Pfade zusätzlich gerendert werden sollen.

Die Option nitro.prerender.routes in nuxt.config.ts nimmt entweder eine feste Liste von Pfaden oder eine Funktion entgegen, die zur Build Zeit dynamisch alle IDs aus der Datenquelle lädt und daraus die vollständige Pfadliste erzeugt. Dieses Muster ist besonders wichtig bei Blogs, Produktkatalogen oder Dokumentationsseiten mit hunderten Unterseiten, bei denen ein manuelles Pflegen der Routenliste unrealistisch wäre.

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      // Crawl links automatically, plus explicitly discovered routes
      crawlLinks: true,
      routes: await getAllBlogSlugs()
    }
  }
})

// Dynamically fetch all slugs at build time
async function getAllBlogSlugs() {
  const posts = await $fetch('https://api.example.com/posts')
  // Turn each post id into a concrete route to prerender
  return posts.map((post) => `/blog/${post.slug}`)
}

4. Routen-Regeln: Hybrid Rendering pro Pfad

Nuxt 3 erlaubt es, für jede Route einzeln festzulegen, wie sie gerendert werden soll, über die routeRules Option in nuxt.config.ts. Für ein primär statisches Projekt lassen sich einzelne Pfade dennoch von der Prerendering Pflicht ausnehmen oder mit einem eigenen Caching Verhalten versehen. Diese Feinsteuerung ist besonders wertvoll, wenn ein sonst komplett statisches Nuxt 3 Projekt eine einzelne serverseitige API Route für ein Kontaktformular oder einen Webhook benötigt.

Wichtig für Static Site Generation im engeren Sinn: Sobald eine Route mit ssr: false markiert wird, deaktiviert sie serverseitiges Rendering für genau diesen Pfad und liefert stattdessen eine minimale HTML Shell aus, die clientseitig hydratisiert wird. Das ist sinnvoll für Bereiche wie ein Admin Dashboard hinter einem Login, das ohnehin nicht öffentlich indexiert werden soll und dessen Inhalte erst nach der Authentifizierung sichtbar werden.

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // Homepage and blog fully prerendered as static HTML
    '/': { prerender: true },
    '/blog/**': { prerender: true },

    // Admin area rendered client side only, no prerendering
    '/admin/**': { ssr: false },

    // Contact API route stays server rendered even in a static build
    '/api/contact': { cors: true }
  }
})

5. Deployment auf Netlify

Netlify erkennt einen Nuxt 3 Static Site Generation Build automatisch, wenn der Build Befehl auf nuxt generate und das Publish Verzeichnis auf .output/public gesetzt ist. Der große Vorteil bei Netlify ist die native Integration von Deploy Previews: Jeder Pull Request erzeugt automatisch eine eigene Vorschau URL mit dem generierten statischen Build, was Code Reviews erheblich erleichtert, weil Reviewer die Änderung direkt live sehen, ohne lokal etwas ausführen zu müssen.

Für Formulare ohne Backend bietet Netlify eine eigene Form Handling Funktion, die sich gut mit einem rein statischen Nuxt 3 Build kombinieren lässt, da kein eigener Server für die Formularverarbeitung nötig ist. Redirects und Header Regeln werden über eine netlify.toml Datei im Projektroot definiert, die parallel zur Nuxt Konfiguration gepflegt wird und unabhängig vom Nuxt Build funktioniert.

# netlify.toml
[build]
  command = "npm run generate"
  publish = ".output/public"

[build.environment]
  NODE_VERSION = "20"

[[redirects]]
  from = "/old-page"
  to = "/new-page"
  status = 301

[[headers]]
  for = "/_nuxt/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

6. Deployment auf Vercel

Vercel erkennt Nuxt 3 Projekte ebenfalls automatisch und bietet für Static Site Generation Builds eine besonders enge Integration mit dem Nitro Preset für Vercel. Wichtig ist, dass für rein statische Deployments explizit nuxt generate als Build Befehl konfiguriert wird, da Vercel standardmäßig sonst den hybriden Server Modus mit Serverless Functions aktiviert, was für ein reines Static Hosting nicht nötig ist und zusätzliche Kosten verursachen kann.

Environment Variablen werden im Vercel Dashboard gepflegt und stehen während des Build Prozesses zur Verfügung, etwa für API Endpunkte, aus denen Prerendering Routen dynamisch geladen werden. Vercel bietet zusätzlich automatische Preview Deployments pro Branch, was in Kombination mit Nuxt 3 Static Site Generation ein schnelles Feedback für jede Änderung ermöglicht, ohne dass ein separates Staging System betrieben werden muss.

{
  "buildCommand": "nuxt generate",
  "outputDirectory": ".output/public",
  "framework": null,
  "installCommand": "npm ci"
}

7. Deployment auf Cloudflare Pages

Cloudflare Pages ist eine gute Wahl für Static Site Generation Projekte, die von einem besonders großen globalen Edge Netzwerk profitieren wollen. Der Build Befehl bleibt identisch zu den anderen Plattformen, nuxt generate, mit dem Ausgabeverzeichnis .output/public. Ein Vorteil von Cloudflare Pages ist die enge Integration mit Cloudflare Workers, falls später einzelne dynamische Funktionen ergänzt werden sollen, ohne die restliche Architektur zu ändern.

Für Projekte mit strengen Datenschutz Anforderungen innerhalb der EU ist relevant, dass Cloudflare mit Regionaldiensten arbeitet, die eine Einschränkung der Datenverarbeitung auf europäische Rechenzentren erlauben. Das unterscheidet Cloudflare Pages von anderen Anbietern, bei denen eine solche regionale Einschränkung nicht immer granular konfigurierbar ist. Für ein Team, das bereits DNS und CDN über Cloudflare betreibt, ist die zusätzliche Integration von Cloudflare Pages für den statischen Nuxt 3 Build meist der Weg mit den wenigsten zusätzlichen Vertragspartnern.

# Cloudflare Pages build configuration (dashboard settings)
Build command:      npm run generate
Build output dir:   .output/public
Root directory:      /
Node.js version:     20

# Manual deployment via Wrangler CLI as an alternative
npx wrangler pages deploy .output/public --project-name=my-nuxt-site

8. Typische Fallstricke bei statischem Deployment

Der häufigste Fehler bei Static Site Generation mit Nuxt 3 ist das Vergessen von dynamischen Prerender Routen. Ohne die explizite nitro.prerender.routes Konfiguration werden nur Seiten erzeugt, die der Crawler über Links findet. Wenn eine Detailseite nirgends verlinkt ist, etwa weil sie nur über eine direkte URL aufgerufen wird, fehlt sie im generierten Build vollständig und liefert später einen 404 Fehler auf dem Static Host.

Ein zweiter typischer Fallstrick betrifft useState und andere serverseitig geteilte Zustände. Bei Static Site Generation läuft jede Seite als isolierter Prerendering Vorgang, weshalb globaler Zustand zwischen verschiedenen Seiten während der Generierung nicht wie bei einem klassischen Server geteilt wird. Ein dritter Fehler ist die Nutzung von absoluten, umgebungsabhängigen URLs in API Aufrufen während des Builds, was in der CI Umgebung anders auflöst als lokal und zu leeren Daten im generierten HTML führen kann, ohne dass ein sichtbarer Build Fehler entsteht.

9. Static Hosts im direkten Vergleich

Alle drei vorgestellten Plattformen unterstützen Static Site Generation mit Nuxt 3 zuverlässig, unterscheiden sich aber in Details, die je nach Projektanforderung den Ausschlag geben können.

In der Praxis entscheidet oft die bestehende Infrastruktur eines Teams über die Plattformwahl. Wer bereits Cloudflare für DNS nutzt, bleibt meist bei Cloudflare Pages. Teams mit engem Bezug zum Vercel Ökosystem und häufigem Wechsel zwischen SSR und Static Site Generation profitieren von der nahtlosen Nitro Integration bei Vercel. Netlify bleibt eine solide, plattformunabhängige Wahl mit besonders ausgereiften Deploy Preview Funktionen für Teams mit intensivem Review Prozess.

10. Zusammenfassung

Static Site Generation mit Nuxt 3 löst zuverlässig das Problem, wie Anwendungen ohne Node.js Betrieb ausgeliefert werden können. nuxt generate crawlt alle erreichbaren Routen automatisch, während dynamische Routen mit nitro.prerender.routes explizit ergänzt werden müssen. Routen-Regeln erlauben hybride Konfigurationen, bei denen einzelne Pfade weiterhin serverseitig oder rein clientseitig laufen, während der Rest der Anwendung vollständig statisch bleibt.

Netlify, Vercel und Cloudflare Pages unterstützen alle diesen Workflow mit nahezu identischer Build Konfiguration, unterscheiden sich aber in Details wie Preview Deployments, Formular Handling und regionalen Datenschutz Optionen. Die Wahl der Plattform sollte sich an der vorhandenen Infrastruktur des Teams orientieren, während die technische Grundlage, ein sauber konfigurierter nuxt generate Build mit vollständigem Prerendering, projektübergreifend gleich bleibt.

11. FAQ: Nuxt 3 SSG Deployment auf Static Hosts