Astro SSR und Hybrid Rendering
Astro unterstützt drei Rendering-Modi: vollständig statisch (SSG), vollständig server-seitig (SSR) und hybrid — eine Kombination aus beiden. Hybrid Rendering ist für die meisten realen Websites die sinnvollste Option: öffentliche Content-Seiten werden statisch vorgerendert, Auth-Bereiche und dynamische Features laufen über SSR.
Die drei Rendering-Modi
Static (SSG)
output: ‘static’ — Alle Seiten beim Build zu HTML, kein Server nötig
Server (SSR)
output: ‘server’ — Alle Seiten per Request gerendert, Server erforderlich
Hybrid
output: ‘server’ + prerender = true — Seiten individuell static oder SSR, Server erforderlich
Hybrid Rendering in der Praxis
Mit output: 'server' in astro.config.mjs ist SSR der Default. Einzelne Routen können mit export const prerender = true als statisch markiert werden — sie werden beim Build zu HTML vorgerendert und als statische Dateien ausgeliefert. Das Gegenteil ist ebenfalls möglich: mit output: 'static' als Default können einzelne Routen mit export const prerender = false auf SSR umgestellt werden.
Wann welcher Modus?
prerender = true — statisch vorrendern
Für alle öffentlichen Content-Seiten: Pillar-Seiten, Artikel, Tools, Rechtliches, Startseite. Diese Seiten ändern sich nur bei neuen Deployments, brauchen keine Session-Daten und profitieren maximal von statischer Auslieferung (CDN-cachebar, minimale TTFB).
prerender = false — SSR
Für alles was Session, Cookies, Request-Header oder Echtzeit-Daten braucht: Auth-Routen, App-Seiten, Admin-Bereiche, Kontaktformulare, API-Endpunkte. Diese Seiten müssen pro Request gerendert werden.
Middleware und prerender
Astro Middleware läuft bei SSR-Seiten vor dem Rendering. Bei prerendered Seiten wird Middleware beim Build, nicht zur Laufzeit ausgeführt. Middleware die auf Session-Daten zugreift (Auth-Check) muss mit Astro.isPrerendered abgesichert werden.
Performance-Vorteile von Hybrid Rendering
Statisch vorgerenderte Seiten werden direkt als HTML-Dateien ausgeliefert — ohne Server-Verarbeitung, ohne Datenbankabfragen, ohne Node.js-Overhead. Die TTFB (Time to First Byte) liegt typischerweise unter 50 ms statt 200–500 ms bei SSR. Für eine Content-Website mit Auth-Bereich bedeutet Hybrid Rendering: 90% der Seiten (öffentlicher Content) sind blitzschnell statisch, 10% (App-Bereich) laufen über SSR.
Node-Adapter für SSR
Für SSR und Hybrid Rendering wird der @astrojs/node-Adapter benötigt. Er kompiliert die Astro-Anwendung zu einem Node.js-Server-Bundle das mit PM2 oder direkt mit Node betrieben wird. Zwei Modi: standalone (empfohlen für Produktions-Deployments — ein eigenständiger Node-Server) und middleware (für Integration in bestehende Express/Fastify-Server).
Typisches Hybrid-Setup für Content-Websites
astro.config.mjs konfigurieren
output: 'server', adapter: node({ mode: 'standalone' }). Das macht SSR zum Default für alle Routen.
Öffentliche Seiten prerendern
In jeder öffentlichen Route (Pillar, Artikel, Tools, Startseite): export const prerender = true. Diese Seiten werden beim Build zu statischem HTML.
Auth-Routen als SSR belassen
Auth-Routen, App-Seiten und API-Endpunkte bekommen kein prerender = true — sie bleiben SSR und verarbeiten Session-Daten zur Laufzeit.
Middleware absichern
Middleware die auf Session/Cookies zugreift mit context.isPrerendered absichern: if (context.isPrerendered) return next(). Verhindert Fehler bei statisch vorgerenderten Seiten.
Häufig gestellte Fragen
Kann ich prerender dynamisch steuern?
Nein — prerender ist eine Build-Zeit-Entscheidung, keine Laufzeit-Entscheidung. Der Wert muss als statische Export-Konstante definiert sein. Dynamisches prerender basierend auf Laufzeit-Bedingungen ist nicht möglich.
Wie teste ich SSR-Seiten lokal?
Mit astro dev laufen auch SSR-Seiten lokal — der Dev-Server simuliert SSR ohne Build. Für Production-nahes Testing: npm run build, dann node dist/server/entry.mjs startet den Production-Server lokal.
Funktioniert Astro Islands mit SSR?
Ja — Islands Architecture funktioniert in allen Rendering-Modi. Auch SSR-Seiten können Islands einbinden. Der Unterschied: Bei SSR wird das HTML pro Request generiert, bei Static beim Build. Die Islands-Hydratisierung im Browser ist identisch.
Welche Umgebungsvariablen brauche ich für Astro SSR?
Mindestens PORT (Standard: 4321 dev, 3000 production) und HOST (Standard: localhost — für Production auf 0.0.0.0 setzen damit externe Verbindungen funktionieren). Datenbankverbindungen (DATABASE_URL, etc.) als separate Variablen in .env definieren.