Astro SSR vollständig konfigurieren: SSR in 3 Schritten aktivieren und Technologie-Entscheidungen klären

Ihr Astro-Blog läuft blitzschnell, Lighthouse 95+ – und plötzlich sagt der Chef: „Wir brauchen Login.“ Statische Site und Nutzer-Login? In der Doku warten SSR, SSG, Hybrid, Adapter – und alles wirkt auf einmal.

So ging es mir beim ersten Astro-SSR-Kontakt. Astro wirbt mit „schnell“ – wird SSR langsamer? Vercel, Netlify, Node.js – welcher Adapter? Was bedeuten output und prerender?

SSR in Astro ist weniger komplex, als es klingt. Dieser Artikel erklärt klar: wann SSR statt SSG nötig ist, wie Sie Adapter schnell konfigurieren und SSR plus SSG im Hybrid-Modus kombinieren. Danach entscheiden Sie selbstständig und sind in etwa 30 Minuten startklar.

Kapitel 1: SSR-Grundlagen und Technologie-Entscheidung

Wann brauchen Sie SSR statt SSG?

Die einfachste Regel: Steht der Inhalt beim Build fest – oder kann er sich bei jedem Besuch ändern?

SSG (Static Site Generation) ist wie vorbereitete Menüs: morgens gekocht, beim Gast sofort serviert – sehr schnell. Blogartikel, Produktseiten, Über uns – wenig Änderung, SSG passt.

SSR (Server-Side Rendering) ist à la carte: nach Bestellung frisch zubereitet. „Willkommen zurück, Max“, Echtzeitkurse, Warenkorbmenge – pro Nutzer unterschiedlich, daher SSR.

Trifft einer der folgenden fünf Fälle zu, sollten Sie SSR prüfen:

1. Authentifizierung und personalisierte Inhalte

Typisch: Login. Beim Build wissen Sie nicht, wer sich anmeldet. Bei einer Lernplattform zeigte die Startseite „Weiterlernen: Lektion 5“ – SSR aus dem individuellen Fortschritt.

2. Echtzeitdaten

Wetter, Börse, Sport-Ergebnisse – minütliche Updates. Nicht jede Minute neu bauen. Mit SSR holen Sie bei jedem Besuch aktuelle Daten.

3. Datenbankabfragen

Produktsuche: jedes Keyword andere Ergebnisse – alle Kombinationen vorab unmöglich. SSR: Suche in Echtzeit gegen die DB.

4. API-Routen

Formulare, Uploads, Drittanbieter-APIs brauchen Backend-Logik. Astro SSR erlaubt API-Routen (src/pages/api/xxx.js) ohne separaten Server.

5. A/B-Tests und personalisierte Empfehlungen

Inhalt nach Geo, Zeit, Verhalten – wie Startseiten großer Marktplätze. Diese Personalisierung braucht SSR.

Manche fragen: „Kann die Blog-Detailseite SSR?“ Ja – aber unnötig. Fester Artikelinhalt, SSG als statisches HTML über CDN – schneller und günstiger. SSR ist kein Selbstzweck.

Hybrid-Modus: beides kombinieren

Seit Astro 2.0: statische Seiten SSG, dynamische SSR. Beispiel E-Commerce:

• Startseite, About, Hilfe → SSG (schnelles Laden)
• Login, Nutzerbereich, Warenkorb → SSR (dynamisch)
• Produktdetail → SSG (fester Inhalt)
• Suchergebnisse → SSR (Live-Abfrage)

Statische Geschwindigkeit bleibt, dynamische Funktionen funktionieren. Ein Bekannter nutzt SSG für Liste und Artikel, SSR für Kommentare – Lighthouse weiterhin 95+.

Kapitel 2: Schnellstart – SSR in 3 Schritten

Astro SSR von null (Node.js-Adapter)

Nach der Entscheidung für SSR starten wir mit dem Node.js-Adapter – universell für Self-Hosting oder VPS.

Schritt 1: Adapter per Befehl installieren

Im Projektroot:

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

npx astro add node

Das erledigt automatisch:

1. Installation von @astrojs/node
2. Anpassung von astro.config.mjs
3. Update der package.json-Abhängigkeiten

Grüne Häkchen in der Konsole = Erfolg. Manuell (z. B. feste Version):

npm install @astrojs/node

Dann die Config manuell anpassen (nächster Schritt).

Schritt 2: Konfigurationsdatei anpassen

In astro.config.mjs (nach Auto-Setup oft schon vorhanden):

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server', // SSR-Modus
  adapter: node({
    mode: 'standalone' // Standalone-Server
  }),
});

Wichtige Optionen:

output:

• 'static' (Standard): alles SSG, reines HTML
• 'server': alles SSR, pro Request dynamisch
• 'hybrid': Standard SSG, pro Seite SSR möglich (empfohlen)

mode:

• 'standalone': eigener Node.js-Server von Astro
• 'middleware': Middleware für Express, Koa usw.

Meist standalone – der Astro-Server reicht. Bestehendes Express-Backend: middleware.

Schritt 3: Build und Start

npm run build

Unter dist/ erscheint server/entry.mjs – Einstieg für SSR.

Server starten:

node ./dist/server/entry.mjs

Standard: http://localhost:4321. Alle Seiten laufen dann per SSR.

Entwicklung

Ohne jedes Mal zu bauen:

npm run dev

Dev-Server unterstützt SSR mit Hot Reload.

Häufige Probleme

1. Port belegt – Umgebungsvariable setzen:

   PORT=3000 node ./dist/server/entry.mjs

2. Adapter-Modul fehlt – @astrojs/node installiert? npm install erneut ausführen

3. 404 – Dateien unter src/pages/ und Astro-Routing prüfen; SSR folgt denselben Regeln

SSR-Setup ist wirklich so kurz – beim ersten Mal unter fünf Minuten bis zum Lauf. Für Vercel oder Netlify gibt es eigene Adapter – Kapitel 3.

Kapitel 3: Adapter im Detail

Vercel, Netlify, Cloudflare – Auswahl

Hosting auf Vercel, Netlify oder Cloudflare? SSR wird einfacher – offizielle Adapter, Deploy mit wenig Aufwand.

Vercel-Adapter – Serverless

Vercel: großzügiges Free-Tier, einfache Konfiguration:

npx astro add vercel

Config-Beispiel:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Vercel-Besonderheit: ISR (Incremental Static Regeneration)

Erster Besuch: SSR; danach Cache für eine Zeit – erneut generieren nach Ablauf.

adapter: vercel({
  isr: {
    expiration: 60, // Cache 60 Sekunden
  },
}),

News-Detail: minütliches Update reicht – ISR verbindet SSR-Flexibilität mit SSG-Geschwindigkeit.

Vercel-Deploy:

1. Adapter konfigurieren
2. Code nach GitHub pushen
3. Projekt in Vercel importieren
4. Build: npm run build (automatisch erkannt)
5. Deploy

Netlify-Adapter – Edge Functions

Beliebt für statische Sites plus dynamische Features:

npx astro add netlify

// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true, // Edge-Middleware
  }),
});

edgeMiddleware

Middleware-Logik (Auth, Redirects) am Edge – schnellere Antwort. Nützlich bei geo-basierten Features (Sprache nach Standort).

Netlify-Redirects

/old-page → /new-page per _redirects im Projektroot:

/old-page  /new-page  301

Nach Deploy aktiv – ohne Codeänderung.

Cloudflare-Adapter – globales CDN

Weltweite Nutzer: Cloudflare Workers in 300+ Rechenzentren, niedrige Latenz.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

npx astro add cloudflare

// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Cloudflare-Einschränkungen

Workers ≠ vollständiges Node.js – z. B. kein fs. Projekte mit solchen APIs: Cloudflare prüfen.

Adapter-Vergleich

Empfehlungen:

• Blog, Docs: Vercel oder Netlify – Free reicht oft
• E-Commerce, SaaS: Vercel (ISR) oder Node.js Self-Hosting
• International: Cloudflare
• Enterprise: Node.js Self-Hosting (Datenschutz, Kontrolle)

Kein absolutes Urteil – abhängig von Anforderungen und Budget. Eigener Blog auf Vercel, Kunden-Sites Self-Hosted – beides funktioniert gut.

Kapitel 4: Hybrid-Rendering in der Praxis

SSR und SSG in einem Projekt

Nach reiner SSR-Konfiguration der Kern: Hybrid-Modus – SSG-Geschwindigkeit plus SSR-Flexibilität.

Hybrid konfigurieren

output auf 'hybrid':

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'hybrid', // Standard SSG, SSR nach Bedarf
  adapter: node(),
});

Danach sind alle Seiten standardmäßig SSG – SSR pro Seite aktivieren.

Rendering pro Seite

SSR für eine Seite – im Frontmatter:

// src/pages/dashboard.astro (SSR)

---

export const prerender = false; // Kein Pre-Render → SSR
const user = Astro.cookies.get('user');

---

<h1>Willkommen zurück, {user?.name}</h1>
<p>Sie haben {user?.notifications} ungelesene Nachrichten</p>

prerender = false: nicht beim Build, sondern bei Request generieren.

Bei output: 'server' (alles SSR) einzelne Seite statisch:

// src/pages/about.astro (SSG)

---

export const prerender = true; // Beim Build generieren

---

<h1>Über uns</h1>
<p>Fester Inhalt – vorab gebaut, schneller Zugriff.</p>

Kurzüberblick (nicht verwechseln):

Merksatz: hybrid = SSG zuerst, server = SSR zuerst.

Praxis: Blog plus Nutzersystem

Struktur:

src/pages/
├── index.astro          // Start (SSG)
├── about.astro          // Über uns (SSG)
├── blog/
│   ├── [slug].astro     // Artikel (SSG)
│   └── index.astro      // Liste (SSG)
├── login.astro          // Login (SSR)
├── dashboard.astro      // Dashboard (SSR)
└── api/
    └── comments.js      // Kommentar-API (SSR)

Config:

// astro.config.mjs
export default defineConfig({
  output: 'hybrid',
  adapter: vercel(),
});

Statische Seite (Standard SSG):

// src/pages/blog/[slug].astro

---

// Kein prerender – in hybrid = SSG
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;

---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

Dynamische Seite (SSR):

// src/pages/dashboard.astro

---

export const prerender = false;

const token = Astro.cookies.get('token')?.value;
if (!token) {
  return Astro.redirect('/login');
}

const user = await fetch(`https://api.example.com/user`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(res => res.json());

---

<div>
  <h1>Willkommen, {user.name}</h1>
  <p>E-Mail: {user.email}</p>
  <p>Letzter Login: {user.lastLogin}</p>
</div>

API-Route (automatisch SSR):

// src/pages/api/comments.js
export async function POST({ request }) {
  const { articleId, content } = await request.json();

  await db.comments.insert({
    articleId,
    content,
    createdAt: new Date(),
  });

  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
}

export async function GET({ url }) {
  const articleId = url.searchParams.get('articleId');

  const comments = await db.comments.findMany({
    where: { articleId },
    orderBy: { createdAt: 'desc' }
  });

  return new Response(JSON.stringify(comments), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Vorteile:

1. Statische Seiten – Lighthouse 95+, CDN
2. Dynamische Seiten – individuelle Daten pro Nutzer
3. API-Routen – Backend ohne separaten Server
4. Kurze Build-Zeit – nur statische Seiten pre-rendern

Ein Projekt: 50 Blogartikel plus Nutzersystem – Build ~20 Sekunden, statische Seiten sofort, dynamische Antwort oft unter 100 ms. Hybrid als Best Practice.

Kapitel 5: FAQ und Best Practices

Fallstricke bei der SSR-Konfiguration

Typische Probleme und Lösungen aus der Praxis.

Problem 1: Astro.clientAddress is only available when using output: 'server'

Ursache: Astro.clientAddress genutzt, aber output noch 'static'.

Lösung:

// astro.config.mjs
export default defineConfig({
  output: 'server', // oder 'hybrid'
  adapter: node(),
});

Astro.clientAddress, Astro.cookies, Astro.redirect() – nur im SSR-Modus.

Problem 2: 404 nach Deploy, lokal OK

Ursache: falscher Adapter oder Build-/Output-Einstellungen der Plattform.

Lösung:

Vercel:

• Build: npm run build
• Output: .vercel/output (automatisch)
• Routing nicht manuell in vercel.json – Astro überlässt

Netlify:

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

• Build: npm run build
• Publish: dist (statisch) oder .netlify (SSR)
• Bei 404 netlify.toml prüfen:

  [build]
    command = "npm run build"
    publish = "dist"

Problem 3: SSR-Seite langsam (> 2 s)

Ursache: schwache Server-Hardware oder langsame DB-Queries.

Lösung:

1. Caching:

   // src/pages/api/news.js
   export async function GET() {
     const cached = await redis.get('news');
     if (cached) {
       return new Response(cached, {
         headers: {
           'Content-Type': 'application/json',
           'Cache-Control': 'public, max-age=60'
         }
       });
     }
   
     const news = await fetchNewsFromDB();
     await redis.set('news', JSON.stringify(news), 'EX', 60);
   
     return new Response(JSON.stringify(news), {
       headers: {
         'Content-Type': 'application/json',
         'Cache-Control': 'public, max-age=60'
       }
     });
   }

2. DB optimieren: Indizes, weniger JOINs, nur benötigte Felder

3. ISR auf Vercel:

   adapter: vercel({
     isr: { expiration: 300 }
   }),

Problem 4: Umgebungsvariablen im Client nicht verfügbar

Ursache: Astro trennt Server- und Client-Env.

Lösung:

Server (SSR, API):

const secret = import.meta.env.SECRET_KEY;

Client (Browser):

const apiUrl = import.meta.env.PUBLIC_API_URL; // Prefix PUBLIC_

.env:

SECRET_KEY=abc123
PUBLIC_API_URL=https://api.example.com

Problem 5: adapter.setApp is not a function

Ursache: inkompatible Astro- und Adapter-Versionen.

Lösung:

npm update astro @astrojs/node

# oder explizit latest
npm install astro@latest @astrojs/node@latest

Astro und Adapter möglichst auf kompatiblen Stand halten.

Best Practices

1. Standard Hybrid – außer jede Seite braucht SSR
2. SSR gezielt – nur prerender = false wo nötig
3. Assets in public/ – CDN, nicht SSR
4. Cache/ISR für selten wechselnde dynamische Listen
5. Env trennen – Secrets serverseitig, PUBLIC_ für Client
6. Monitoring – Vercel Analytics oder GA für SSR-Latenz

Fazit

Kern in drei Sätzen:

1. SSR ist kein Allheilmittel – gezielt einsetzen

Statische Seiten SSG, dynamische SSR – Hybrid für die meisten Projekte. Ganzer Blog auf SSR verschlechtert oft die Performance – Blog-Inhalt unverändert, SSG über CDN schneller.

2. Adapter nach Deploy-Plattform – Konfiguration ist einfach

Vercel/Netlify/Cloudflare: npx astro add [platform]. Self-Hosting: npx astro add node in Minuten. Praxis schlanker als die Doku vermuten lässt.

3. Hybrid verbindet beides

Astros Stärke: statische Seiten mit 95+ Lighthouse, dynamische mit Personalisierung – Build-Zeit und Kosten im Griff. Hybrid ist meine erste Wahl.

Nächste Schritte

1. Ausprobieren: npx astro add node – SSR in fünf Minuten
2. Bedarf klären: welche Seiten dynamisch, welche statisch
3. Vertiefen: Server Islands – SSR-Komponenten in SSG-Seiten

Bei Problemen: Astro Discord – schnelle Antworten, hilfsbereite Community.

Nicht überoptimieren: unter ~10.000 PV/Tag reicht oft eine statische Site – SSR erhöht Komplexität ohne Nutzen. Technologie dient dem Business.

Viel Erfolg bei der Konfiguration – Fragen gerne in den Kommentaren!