# BizMatch SSR - Technische Dokumentation
## Was ist Server-Side Rendering (SSR)?
Server-Side Rendering bedeutet, dass die Angular-Anwendung nicht nur im Browser, sondern auch auf dem Server läuft und HTML vorab generiert.
---
## Unterschied: SPA vs. SSR vs. Prerendering
### 1. Single Page Application (SPA) - OHNE SSR
**Ablauf:**
```
Browser → lädt index.html
→ index.html enthält nur
→ lädt JavaScript-Bundles
→ JavaScript rendert die Seite
```
**HTML-Response:**
```html
BizMatch
```
**Nachteile:**
- ❌ Suchmaschinen sehen leeren Content
- ❌ Langsamer "First Contentful Paint"
- ❌ Schlechtes SEO
- ❌ Kein Social-Media-Preview (Open Graph)
---
### 2. Server-Side Rendering (SSR)
**Ablauf:**
```
Browser → fragt Server nach /business/123
→ Server rendert Angular-App mit Daten
→ Server sendet vollständiges HTML
→ Browser zeigt sofort Inhalt
→ JavaScript lädt im Hintergrund
→ Anwendung wird "hydrated" (interaktiv)
```
**HTML-Response:**
```html
Restaurant "Zum Löwen" | BizMatch
Restaurant "Zum Löwen"
Traditionelles deutsches Restaurant...
```
**Vorteile:**
- ✅ Suchmaschinen sehen vollständigen Inhalt
- ✅ Schneller First Contentful Paint
- ✅ Besseres SEO
- ✅ Social-Media-Previews funktionieren
**Nachteile:**
- ⚠️ Komplexere Konfiguration
- ⚠️ Server-Ressourcen erforderlich
- ⚠️ Code muss browser- und server-kompatibel sein
---
### 3. Prerendering (Static Site Generation)
**Ablauf:**
```
Build-Zeit → Rendert ALLE Seiten zu statischen HTML-Dateien
→ /business/123.html, /business/456.html, etc.
→ HTML-Dateien werden auf CDN deployed
```
**Unterschied zu SSR:**
- Prerendering: HTML wird **zur Build-Zeit** generiert
- SSR: HTML wird **zur Request-Zeit** generiert
**BizMatch nutzt SSR, NICHT Prerendering**, weil:
- Listings dynamisch sind (neue Einträge täglich)
- Benutzerdaten personalisiert sind
- Suche und Filter zur Laufzeit erfolgen
---
## Wie funktioniert SSR in BizMatch?
### Architektur-Überblick
```
┌─────────────────────────────────────────────────────────────┐
│ Browser Request │
│ GET /business/restaurant-123 │
└────────────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Express Server │
│ (server.ts:30-41) │
├─────────────────────────────────────────────────────────────┤
│ 1. Empfängt Request │
│ 2. Ruft AngularNodeAppEngine auf │
│ 3. Rendert Angular-Komponente serverseitig │
│ 4. Sendet HTML zurück │
└────────────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ AngularNodeAppEngine │
│ (@angular/ssr/node) │
├─────────────────────────────────────────────────────────────┤
│ 1. Lädt main.server.ts │
│ 2. Bootstrapped Angular in Node.js │
│ 3. Führt Routing aus (/business/restaurant-123) │
│ 4. Rendert Component-Tree zu HTML-String │
│ 5. Injiziert Meta-Tags, Titel │
└────────────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Angular Application │
│ (Browser-Code im Server) │
├─────────────────────────────────────────────────────────────┤
│ • Komponenten werden ausgeführt │
│ • API-Calls werden gemacht (TransferState) │
│ • DOM wird SIMULIERT (ssr-dom-polyfill.ts) │
│ • HTML-Output wird generiert │
└─────────────────────────────────────────────────────────────┘
```
---
## Wichtige Dateien und ihre Rolle
### 1. `server.ts` - Express Server
```typescript
const angularApp = new AngularNodeAppEngine();
server.get('*', (req, res, next) => {
angularApp.handle(req) // ← Rendert Angular serverseitig
.then((response) => {
if (response) {
writeResponseToNodeResponse(response, res);
}
});
});
```
**Rolle:**
- HTTP-Server (Express)
- Nimmt Requests entgegen
- Delegiert an Angular SSR Engine
- Sendet gerenderte HTML-Responses zurück
---
### 2. `src/main.server.ts` - Server Entry Point
```typescript
import './ssr-dom-polyfill'; // ← WICHTIG: DOM-Mocks laden
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { config } from './app/app.config.server';
const bootstrap = () => bootstrapApplication(AppComponent, config);
export default bootstrap;
```
**Rolle:**
- Entry Point für SSR
- Lädt DOM-Polyfills **VOR** allen anderen Imports
- Bootstrapped Angular im Server-Kontext
---
### 3. `dist/bizmatch/server/index.server.html` - Server Template
**WICHTIG:** Diese Datei wird **beim Build erstellt**, nicht manuell geschrieben!
```bash
# Build-Prozess erstellt automatisch:
npm run build:ssr
→ dist/bizmatch/server/index.server.html ✅
→ dist/bizmatch/server/server.mjs ✅
→ dist/bizmatch/browser/index.csr.html ✅
```
**Quelle:**
- Angular nimmt `src/index.html` als Vorlage
- Fügt SSR-spezifische Meta-Tags hinzu
- Generiert `index.server.html` für serverseitiges Rendering
- Generiert `index.csr.html` für clientseitiges Rendering (Fallback)
**Warum nicht im Git?**
- Build-Artefakte werden nicht eingecheckt (`.gitignore`)
- Jeder Build erstellt sie neu
- Verhindert Merge-Konflikte bei generierten Dateien
**Fehlerquelle bei neuem Laptop:**
```
git clone → dist/ Ordner fehlt
→ index.server.html fehlt
→ npm run serve:ssr crasht ❌
Lösung: → npm run build:ssr
→ index.server.html wird erstellt ✅
```
---
### 4. `src/ssr-dom-polyfill.ts` - DOM-Mocks
```typescript
const windowMock = {
document: { createElement: () => ({ ... }) },
localStorage: { getItem: () => null },
navigator: { userAgent: 'node' },
// ... etc
};
if (typeof window === 'undefined') {
(global as any).window = windowMock;
}
```
**Rolle:**
- Simuliert Browser-APIs in Node.js
- Verhindert `ReferenceError: window is not defined`
- Ermöglicht die Ausführung von Browser-Code im Server
- Kritisch für Libraries wie Leaflet, die `window` erwarten
**Warum notwendig?**
- Angular-Code nutzt `window`, `document`, `localStorage`, etc.
- Node.js hat diese APIs nicht
- Ohne Polyfills: Crash beim Server-Start
---
### 4. `ssr-dom-preload.mjs` - Node.js Preload Script
```javascript
import { isMainThread } from 'node:worker_threads';
if (!isMainThread) {
// Skip polyfills in worker threads (sass, esbuild)
} else {
globalThis.window = windowMock;
globalThis.document = documentMock;
}
```
**Rolle:**
- Wird beim `dev:ssr` verwendet
- Lädt DOM-Mocks **VOR** allen anderen Modulen
- Nutzt Node.js `--import` Flag
- Vermeidet Probleme mit early imports
**Verwendung:**
```bash
NODE_OPTIONS='--import ./ssr-dom-preload.mjs' ng serve
```
---
### 5. `app.config.server.ts` - Server-spezifische Config
Enthält Provider, die nur im Server-Kontext geladen werden:
- `provideServerRendering()`
- Server-spezifische HTTP-Interceptors
- TransferState für API-Daten
---
## Rendering-Ablauf im Detail
### Phase 1: Server-Side Rendering
```
1. Request kommt an: GET /business/restaurant-123
2. Express Router:
→ server.get('*', ...)
3. AngularNodeAppEngine:
→ bootstrapApplication(AppComponent, serverConfig)
→ Angular läuft in Node.js
4. Angular Router:
→ Route /business/:slug matched
→ ListingDetailComponent wird aktiviert
5. Component Lifecycle:
→ ngOnInit() wird ausgeführt
→ API-Call: fetch('/api/listings/restaurant-123')
→ Daten werden geladen
→ Template wird mit Daten gerendert
6. TransferState:
→ API-Response wird in HTML injiziert
→
7. Meta-Tags:
→ Title-Service setzt
→ Meta-Service setzt <meta name="description">
8. HTML-Output:
→ Komplettes HTML mit Daten
→ Wird an Browser gesendet
```
**Server-Output:**
```html
<!doctype html>
<html>
<head>
<title>Restaurant "Zum Löwen" | BizMatch