eigenes Server-Side-Rendering ohne Next.js oder Remix aufsetzen
Nicht jedes Projekt braucht ein volles Meta-Framework. Mit renderToPipeableStream auf einem schlanken Express-Server laesst sich Streaming-HTML mit Suspense-Boundaries selbst aufbauen, samt der Stellen, an denen ein eigenes Setup an seine Grenzen stoesst.
Inhaltsverzeichnis
- 1. Warum ueberhaupt eigenes SSR statt eines Meta-Frameworks
- 2. Grundsetup mit Express und renderToPipeableStream
- 3. Streaming mit Suspense-Boundaries im Detail
- 4. Hydration auf dem Client mit hydrateRoot
- 5. Abbruch und Timeout-Handling
- 6. HTTP-Statuscodes und Redirects korrekt steuern
- 7. Bundling und Code-Splitting selbst verantworten
- 8. Wo ein eigenes Setup an Grenzen stoesst
- 9. Vergleich: Eigenes SSR versus Meta-Framework
- 10. Zusammenfassung
- 11. FAQ
1. Warum ueberhaupt eigenes SSR statt eines Meta-Frameworks
Next.js, Remix und aehnliche Meta-Frameworks loesen serverseitiges Rendering zusammen mit Routing, Datenladen, Caching und Deployment in einem einzigen, gut abgestimmten Paket, was fuer die meisten Projekte die richtige Wahl ist. Es gibt aber Situationen, in denen ein eigenes, schlankes SSR-Setup sinnvoller bleibt: die Integration in eine bestehende Express- oder Fastify-Anwendung mit eigener Routing-Logik, ein Embedded-Widget, das nur einen kleinen Teil einer fremden Seite serverseitig rendert, oder ein bewusst minimalistischer Tech-Stack ohne die Build-Pipeline eines Meta-Frameworks.
Die React-API fuer genau diesen Zweck heisst renderToPipeableStream und lebt im Paket react-dom/server, spezifisch fuer Node.js-Umgebungen mit Stream-Unterstuetzung. Sie ersetzt die aeltere, synchrone Funktion renderToString, die den kompletten Baum blockierend in einen String rendert, durch ein Streaming-Modell, das HTML in Chunks an den Client sendet, sobald es verfuegbar ist, statt auf den langsamsten Teil der Seite zu warten.
2. Grundsetup mit Express und renderToPipeableStream
Ein minimaler Server nimmt eine eingehende Anfrage entgegen, ruft renderToPipeableStream mit der Wurzelkomponente der Anwendung und einem Optionen-Objekt auf, das unter anderem den Callback onShellReady definiert, der genau dann feuert, sobald das initiale, nicht in Suspense eingeschlossene HTML fertig berechnet ist. In diesem Callback setzt man den Content-Type-Header und ruft pipe() auf, um den entstehenden Stream direkt an die HTTP-Response weiterzureichen, wodurch der Browser bereits Bytes empfaengt, waehrend React im Hintergrund noch an eventuell vorhandenen Suspense-Inhalten weiterarbeitet.
Wichtig ist die Unterscheidung zwischen onShellReady und onAllReady: onShellReady feuert, sobald das sogenannte Shell fertig ist, also der Teil der Seite ausserhalb aller Suspense-Boundaries, waehrend onAllReady erst feuert, wenn wirklich der komplette Baum inklusive aller aufgeloesten Suspense-Inhalte fertig ist. Fuer Crawler ohne JavaScript-Ausfuehrung oder fuer statische Exporte verwendet man meist onAllReady, fuer die interaktive Auslieferung an echte Browser fast immer onShellReady, damit der Nutzer so schnell wie moeglich sichtbaren Inhalt bekommt.
import express from 'express';
import { renderToPipeableStream } from 'react-dom/server';
import App from './App';
const app = express();
app.get('*', (req, res) => {
const { pipe, abort } = renderToPipeableStream(<App url={req.url} />, {
bootstrapScripts: ['/client.js'],
onShellReady() {
res.statusCode = 200;
res.setHeader('Content-Type', 'text/html; charset=utf-8');
pipe(res);
},
onShellError(error) {
res.statusCode = 500;
res.setHeader('Content-Type', 'text/html; charset=utf-8');
res.send('<!doctype html><p>Etwas ist schiefgelaufen.</p>');
},
onError(error) {
console.error(error);
},
});
setTimeout(abort, 10000);
});
app.listen(3000);
3. Streaming mit Suspense-Boundaries im Detail
Der eigentliche Vorteil von renderToPipeableStream zeigt sich erst mit Suspense-Boundaries innerhalb des Komponentenbaums: Jede Komponente, die durch eine Suspense-Boundary umschlossen ist und beim serverseitigen Rendern noch auf Daten wartet, wird zunaechst durch ihren fallback ersetzt, waehrend der Rest der Seite bereits als initiales HTML ausgeliefert wird. Sobald die wartenden Daten verfuegbar sind, sendet React ein zusaetzliches Inline-Script als weiteren Chunk desselben Streams, das den vorher gerenderten Platzhalter im Browser per DOM-Manipulation gegen den tatsaechlichen Inhalt austauscht.
Dieser Mechanismus funktioniert vollstaendig ohne zusaetzliches Client-JavaScript-Framework, weil React die dafuer noetigen kleinen Steuerungs-Skripte selbst in den Stream einbettet. Aus Sicht der Anwendungsentwicklung bedeutet das, dass man einfach eine langsame Datenquelle, etwa eine externe API mit hoher Latenz, in eine eigene Suspense-Boundary mit einem sinnvollen Skeleton-Fallback einschliesst, und React kuemmert sich automatisch darum, dass der Rest der Seite nicht auf diese eine langsame Quelle warten muss.
import { Suspense } from 'react';
function ProductPage({ productId }) {
return (
<main>
<ProductHeader productId={productId} />
<Suspense fallback={<ReviewsSkeleton />}>
<ProductReviews productId={productId} />
</Suspense>
<Suspense fallback={<RecommendationsSkeleton />}>
<RelatedProducts productId={productId} />
</Suspense>
</main>
);
}
// ProductReviews und RelatedProducts lesen Daten ueber
// eine Suspense-kompatible Datenquelle, z.B. React 19 use()
function ProductReviews({ productId }) {
const reviews = use(fetchReviews(productId));
return <ul>{reviews.map((r) => <li key={r.id}>{r.text}</li>)}</ul>;
}
4. Hydration auf dem Client mit hydrateRoot
Das vom Server gestreamte HTML ist zunaechst statisches Markup ohne Interaktivitaet, bis der Client das mit bootstrapScripts referenzierte JavaScript-Bundle laedt und dort hydrateRoot aus react-dom/client aufruft. Diese Funktion nimmt dieselbe Komponente entgegen, die auch serverseitig gerendert wurde, und heftet React-Event-Handler an die bereits vorhandenen DOM-Knoten, statt sie wie bei einem reinen Client-Side-Rendering neu zu erzeugen, was fuer die initiale Ladezeit einen erheblichen Unterschied macht.
Eine haeufige Fehlerquelle in eigenen SSR-Setups ist ein Mismatch zwischen dem serverseitig gerenderten Markup und dem, was die Komponente beim ersten Client-Render erzeugen wuerde, etwa weil Datumsformatierung oder zufaellig generierte IDs auf Server und Client unterschiedlich ausfallen. React erkennt solche Hydration-Mismatches, gibt eine Warnung aus und rendert die betroffenen Teile im schlimmsten Fall clientseitig neu, was den Geschwindigkeitsvorteil des Streamings fuer genau diesen Bereich zunichtemacht, weshalb deterministisches Rendering zwischen Server und Client eine Grundvoraussetzung fuer funktionierendes SSR ist.
// client.js
import { hydrateRoot } from 'react-dom/client';
import App from './App';
hydrateRoot(document, <App url={window.location.pathname} />);
5. Abbruch und Timeout-Handling
renderToPipeableStream gibt neben pipe auch eine abort-Funktion zurueck, mit der ein laufendes Rendering gezielt abgebrochen werden kann, typischerweise ueber einen Timeout, der verhindert, dass eine besonders langsame Datenquelle den Server-Request unbegrenzt lange offen haelt. Wird abort aufgerufen, bevor alle Suspense-Inhalte aufgeloest sind, rendert React die noch ausstehenden Bereiche stattdessen clientseitig weiter, sobald die Hydration stattfindet, statt den Request ganz fehlschlagen zu lassen.
Fuer produktionsreife eigene SSR-Setups ist es zusaetzlich wichtig, den onError-Callback zu nutzen, um Fehler waehrend des Streamings zu protokollieren, da diese Fehler anders als bei renderToString nicht zwangslaeufig den gesamten Request scheitern lassen, sondern je nach Position im Baum nur einzelne Suspense-Bereiche betreffen koennen. Ohne dediziertes Error-Logging in onError bleiben solche partiellen Fehler in Produktion leicht unbemerkt, weil die Seite fuer den Nutzer trotzdem weitgehend funktionsfaehig aussieht.
6. HTTP-Statuscodes und Redirects korrekt steuern
Ein Aspekt, den Meta-Frameworks meist automatisch loesen, aber bei eigenem SSR explizit bedacht werden muss, ist die korrekte Steuerung des HTTP-Statuscodes: Da der Response-Header bereits beim ersten pipe()-Aufruf in onShellReady gesetzt werden muss, aber ein 404-Fehler unter Umstaenden erst innerhalb einer tiefer verschachtelten Datenkomponente erkannt wird, braucht man einen Mechanismus, um diese Information rechtzeitig aus dem Komponentenbaum an den Server-Code zurueckzumelden, etwa ueber ein mutable Kontext-Objekt, das waehrend des Renderns befuellt wird und vor dem pipe()-Aufruf ausgewertet wird.
Fuer Redirects gilt dasselbe Problem in verschaerfter Form, da ein Redirect idealerweise passiert, bevor ueberhaupt HTML gestreamt wird. In der Praxis loest man das, indem man kritische, redirect-ausloesende Datenabfragen (etwa eine Authentifizierungspruefung) bereits vor dem Aufruf von renderToPipeableStream ausserhalb der React-Baum-Logik durchfuehrt und nur bei einer positiven Pruefung ueberhaupt mit dem eigentlichen Rendering beginnt, statt zu versuchen, einen Redirect mitten aus dem Komponentenbaum heraus auszuloesen.
7. Bundling und Code-Splitting selbst verantworten
Waehrend renderToPipeableStream das serverseitige Rendering uebernimmt, bleibt die gesamte Build-Pipeline, also das Buendeln des Client-JavaScripts, Code-Splitting fuer einzelne Routen und das Erzeugen der bootstrapScripts-Pfade, vollstaendig Aufgabe des eigenen Setups, meist mit einem Tool wie Vite oder esbuild im Middleware-Modus fuer die Entwicklung und einem separaten Produktions-Build-Schritt. Das ist der Bereich, in dem der Aufwand eines eigenen SSR-Setups am deutlichsten sichtbar wird, weil Meta-Frameworks diese Konfiguration bereits vollstaendig vorwegnehmen.
Besonders bei Code-Splitting nach Routen muss man selbst dafuer sorgen, dass die serverseitig gerenderten Chunk-Referenzen exakt mit den tatsaechlich vom Client geladenen Bundles uebereinstimmen, da ein Mismatch zwischen Server- und Client-Manifest zu fehlenden Skripten oder doppeltem Laden fuehrt. Ein bewaehrter Ansatz ist, waehrend des Produktions-Builds ein Manifest-JSON zu erzeugen, das Komponenten-Importpfade auf die tatsaechlichen, gehashten Bundle-Dateien abbildet, und dieses Manifest zur Laufzeit im Server-Code einzulesen, um die korrekten bootstrapScripts dynamisch zu bestimmen.
8. Wo ein eigenes Setup an Grenzen stoesst
Ein eigenes SSR-Setup mit renderToPipeableStream deckt das Rendering selbst gut ab, loest aber keines der umliegenden Probleme, die Meta-Frameworks zusaetzlich mitbringen: Datei-basiertes Routing, automatische Code-Splitting-Grenzen pro Route, eingebautes Caching von Datenabfragen ueber mehrere Requests hinweg, Bild-Optimierung, inkrementelle statische Regenerierung oder eine fertige Deployment-Integration fuer Edge-Umgebungen. All das muesste im eigenen Setup entweder selbst gebaut oder bewusst weggelassen werden.
Realistisch lohnt sich ein eigenes Setup deshalb vor allem fuer klar abgegrenzte, kleinere Anwendungsfaelle: ein einzelnes SSR-Widget innerhalb einer groesseren, nicht-React-basierten Anwendung, ein internes Tool mit ueberschaubarer Routenzahl, oder ein Lernprojekt, das die Mechanik hinter Next.js besser verstehen soll. Fuer ein vollstaendiges, wachsendes Produkt mit vielen Seiten, Team-Mitgliedern und Deployment-Anforderungen ist der Wartungsaufwand eines eigenen SSR-Setups gegenueber einem etablierten Meta-Framework in den meisten Faellen schwer zu rechtfertigen.
9. Vergleich: Eigenes SSR versus Meta-Framework
Die Entscheidung zwischen einem eigenen SSR-Setup und einem Meta-Framework wie Next.js oder Remix haengt weniger von der reinen React-API ab, renderToPipeableStream ist in beiden Faellen letztlich dieselbe zugrunde liegende Technologie, sondern davon, wie viel der umliegenden Infrastruktur man selbst betreiben und pflegen moechte. Ein eigenes Setup bietet maximale Kontrolle und minimale Abhaengigkeiten, verlangt dafuer aber, jede der oben genannten Zusatzfunktionen bei Bedarf selbst zu implementieren.
Die folgende Tabelle stellt die wichtigsten Unterschiede gegenueber, um bei der Setup-Entscheidung fuer ein konkretes Projekt eine fundierte Grundlage zu haben, statt sich pauschal fuer die eine oder andere Richtung zu entscheiden.
| Kriterium | Eigenes SSR mit renderToPipeableStream | Next.js / Remix | Empfehlung |
|---|---|---|---|
| Kontrolle ueber Server-Integration | Vollstaendig, eigener Express/Fastify-Server | Eingeschraenkt auf Framework-Konventionen | Eigenes Setup bei bestehender Server-Architektur |
| Routing | Muss selbst implementiert werden | Datei-basiert eingebaut | Meta-Framework fuer viele Routen |
| Code-Splitting und Manifest | Manuelle Build-Pipeline noetig | Automatisch geloest | Meta-Framework spart deutlich Aufwand |
| Caching von Datenabfragen | Selbst zu implementieren | Teilweise eingebaut | Meta-Framework fuer datenintensive Apps |
| Bundlegroesse und Abhaengigkeiten | Minimal, nur React und Server-Framework | Groesseres Framework-Gewicht | Eigenes Setup fuer schlanke Widgets |
Mironsoft
React-Architektur, Performance und Magento-Frontend-Integration
React-Frontends, die schnell bleiben statt mit jedem Feature langsamer zu werden?
Wir prüfen bestehende React-Anwendungen auf unnötige Re-Renders, aufgeblähte Bundles und fragile State-Verwaltung und bauen daraus ein Frontend, das performant bleibt und sich sauber an Magento oder andere Backends anbindet.
Performance-Audit
Re-Renders, Bundle-Größe und Ladezeiten systematisch messen und beheben.
State-Architektur
Context, Zustand und Server State sauber trennen statt alles in einen Topf zu werfen.
Magento-Integration
GraphQL- oder REST-Anbindung an Magento robust und typsicher aufbauen.
10. Zusammenfassung
Eigenes SSR mit renderToPipeableStream: Das Wichtigste auf einen Blick
Streaming statt Blockieren
renderToPipeableStream sendet HTML in Chunks, sobald es verfuegbar ist, statt auf den langsamsten Teil zu warten.
Suspense treibt Streaming
Jede Suspense-Boundary wird zunaechst als Fallback ausgeliefert und spaeter per Inline-Script ausgetauscht.
onShellReady vs onAllReady
onShellReady fuer schnelle Auslieferung an Browser, onAllReady fuer Crawler ohne JavaScript-Ausfuehrung.
Infrastruktur bleibt eigene Aufgabe
Routing, Code-Splitting-Manifest und Caching muessen im eigenen Setup selbst gebaut werden.