docs: Add SSR setup guide and update SSR polyfills
- Add SSR_ANLEITUNG.md with step-by-step setup instructions - Add SSR_DOKUMENTATION.md with technical SSR documentation - Update ssr-dom-polyfill.ts for better SSR compatibility - Update ssr-dom-preload.mjs for dev:ssr mode - Update DEPLOYMENT.md with SSR deployment instructions
This commit is contained in:
275
bizmatch/SSR_ANLEITUNG.md
Normal file
275
bizmatch/SSR_ANLEITUNG.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# BizMatch SSR - Schritt-für-Schritt-Anleitung
|
||||
|
||||
## Problem: SSR startet nicht auf neuem Laptop?
|
||||
|
||||
Diese Anleitung hilft Ihnen, BizMatch mit Server-Side Rendering (SSR) auf einem neuen Rechner zum Laufen zu bringen.
|
||||
|
||||
---
|
||||
|
||||
## Voraussetzungen prüfen
|
||||
|
||||
```bash
|
||||
# Node.js Version prüfen (mind. v18 erforderlich)
|
||||
node --version
|
||||
|
||||
# npm Version prüfen
|
||||
npm --version
|
||||
|
||||
# Falls Node.js fehlt oder veraltet ist:
|
||||
# https://nodejs.org/ → LTS Version herunterladen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schritt 1: Repository klonen (falls noch nicht geschehen)
|
||||
|
||||
```bash
|
||||
git clone https://gitea.bizmatch.net/aknuth/bizmatch-project.git
|
||||
cd bizmatch-project/bizmatch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schritt 2: Dependencies installieren
|
||||
|
||||
**WICHTIG:** Dieser Schritt ist essentiell und wird oft vergessen!
|
||||
|
||||
```bash
|
||||
cd ~/bizmatch-project/bizmatch
|
||||
npm install
|
||||
```
|
||||
|
||||
> **Tipp:** Bei Problemen versuchen Sie: `rm -rf node_modules package-lock.json && npm install`
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ WICHTIG: Erstes Setup auf neuem Laptop
|
||||
|
||||
**Wenn Sie das Projekt zum ersten Mal auf einem neuen Rechner klonen, müssen Sie ZUERST einen Build erstellen!**
|
||||
|
||||
```bash
|
||||
cd ~/bizmatch-project/bizmatch
|
||||
|
||||
# 1. Dependencies installieren
|
||||
npm install
|
||||
|
||||
# 2. Build erstellen (erstellt dist/bizmatch/server/index.server.html)
|
||||
npm run build:ssr
|
||||
```
|
||||
|
||||
**Warum?**
|
||||
- Die `dist/` Folder werden NICHT ins Git eingecheckt (`.gitignore`)
|
||||
- Die Datei `dist/bizmatch/server/index.server.html` fehlt nach `git clone`
|
||||
- Ohne Build → `npm run serve:ssr` crasht mit "Cannot find index.server.html"
|
||||
|
||||
**Nach dem ersten Build** können Sie dann Development-Befehle nutzen.
|
||||
|
||||
---
|
||||
|
||||
## Schritt 3: Umgebung wählen
|
||||
|
||||
### Option A: Entwicklung (OHNE SSR)
|
||||
|
||||
Schnellster Weg für lokale Entwicklung:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
- Öffnet automatisch: http://localhost:4200
|
||||
- Hot-Reload aktiv (Code-Änderungen werden sofort sichtbar)
|
||||
- **Kein SSR** (schneller für Entwicklung)
|
||||
|
||||
### Option B: Development mit SSR
|
||||
|
||||
Für SSR-Testing während der Entwicklung:
|
||||
|
||||
```bash
|
||||
npm run dev:ssr
|
||||
```
|
||||
|
||||
- Öffnet: http://localhost:4200
|
||||
- Hot-Reload aktiv
|
||||
- **SSR aktiv** (simuliert Production)
|
||||
- Nutzt DOM-Polyfills via `ssr-dom-preload.mjs`
|
||||
|
||||
### Option C: Production Build mit SSR
|
||||
|
||||
Für finalen Production-Test:
|
||||
|
||||
```bash
|
||||
# 1. Build erstellen
|
||||
npm run build:ssr
|
||||
|
||||
# 2. Server starten
|
||||
npm run serve:ssr
|
||||
```
|
||||
|
||||
- Server läuft auf: http://localhost:4200
|
||||
- **Vollständiges SSR** (wie in Production)
|
||||
- Kein Hot-Reload (für Änderungen erneut builden)
|
||||
|
||||
---
|
||||
|
||||
## Schritt 4: Testen
|
||||
|
||||
Öffnen Sie http://localhost:4200 im Browser.
|
||||
|
||||
### SSR funktioniert, wenn:
|
||||
|
||||
1. **Seitenquelltext ansehen** (Rechtsklick → "Seitenquelltext anzeigen"):
|
||||
- HTML-Inhalt ist bereits vorhanden (nicht nur `<app-root></app-root>`)
|
||||
- Meta-Tags sind sichtbar
|
||||
|
||||
2. **JavaScript deaktivieren** (Chrome DevTools → Settings → Disable JavaScript):
|
||||
- Seite zeigt Inhalt an (wenn auch nicht interaktiv)
|
||||
|
||||
3. **Network-Tab** (Chrome DevTools → Network → Doc):
|
||||
- HTML-Response enthält bereits gerenderten Content
|
||||
|
||||
---
|
||||
|
||||
## Häufige Probleme und Lösungen
|
||||
|
||||
### Problem 1: `npm: command not found`
|
||||
|
||||
**Lösung:** Node.js installieren
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# macOS
|
||||
brew install node
|
||||
|
||||
# Windows
|
||||
# https://nodejs.org/ → Installer herunterladen
|
||||
```
|
||||
|
||||
### Problem 2: `Cannot find module '@angular/ssr'`
|
||||
|
||||
**Lösung:** Dependencies neu installieren
|
||||
|
||||
```bash
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
### Problem 3: `Error: EADDRINUSE: address already in use :::4200`
|
||||
|
||||
**Lösung:** Port ist bereits belegt
|
||||
|
||||
```bash
|
||||
# Prozess finden und beenden
|
||||
lsof -i :4200
|
||||
kill -9 <PID>
|
||||
|
||||
# Oder anderen Port nutzen
|
||||
PORT=4300 npm run serve:ssr
|
||||
```
|
||||
|
||||
### Problem 4: `Error loading @angular/platform-server` oder "Cannot find index.server.html"
|
||||
|
||||
**Lösung:** Build fehlt oder ist veraltet
|
||||
|
||||
```bash
|
||||
# dist-Ordner löschen und neu builden
|
||||
rm -rf dist
|
||||
npm run build:ssr
|
||||
|
||||
# Dann starten
|
||||
npm run serve:ssr
|
||||
```
|
||||
|
||||
**Häufiger Fehler auf neuem Laptop:**
|
||||
- Nach `git pull` fehlt der `dist/` Ordner komplett
|
||||
- `index.server.html` wird beim Build erstellt, nicht ins Git eingecheckt
|
||||
- **Lösung:** Immer erst `npm run build:ssr` ausführen!
|
||||
|
||||
### Problem 5: "Seite lädt nicht" oder "White Screen"
|
||||
|
||||
**Lösung:**
|
||||
|
||||
1. Browser-Cache leeren (Strg+Shift+R / Cmd+Shift+R)
|
||||
2. DevTools öffnen → Console-Tab → Fehler prüfen
|
||||
3. Sicherstellen, dass Backend läuft (falls API-Calls)
|
||||
|
||||
### Problem 6: "Module not found: Error: Can't resolve 'window'"
|
||||
|
||||
**Lösung:** Browser-spezifischer Code wird im SSR-Build verwendet
|
||||
|
||||
- Prüfen Sie `ssr-dom-polyfill.ts` - DOM-Mocks sollten vorhanden sein
|
||||
- Code mit `isPlatformBrowser()` schützen:
|
||||
|
||||
```typescript
|
||||
import { isPlatformBrowser } from '@angular/common';
|
||||
import { PLATFORM_ID } from '@angular/core';
|
||||
|
||||
constructor(@Inject(PLATFORM_ID) private platformId: Object) {}
|
||||
|
||||
ngOnInit() {
|
||||
if (isPlatformBrowser(this.platformId)) {
|
||||
// Nur im Browser ausführen
|
||||
window.scrollTo(0, 0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Production Deployment mit PM2
|
||||
|
||||
Für dauerhaften Betrieb (Server-Umgebung):
|
||||
|
||||
```bash
|
||||
# PM2 global installieren
|
||||
npm install -g pm2
|
||||
|
||||
# Production Build
|
||||
npm run build:ssr
|
||||
|
||||
# Server mit PM2 starten
|
||||
pm2 start dist/bizmatch/server/server.mjs --name "bizmatch"
|
||||
|
||||
# Auto-Start bei Server-Neustart
|
||||
pm2 startup
|
||||
pm2 save
|
||||
|
||||
# Logs anzeigen
|
||||
pm2 logs bizmatch
|
||||
|
||||
# Server neustarten nach Updates
|
||||
npm run build:ssr && pm2 restart bizmatch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Unterschiede der Befehle
|
||||
|
||||
| Befehl | SSR | Hot-Reload | Verwendung |
|
||||
|--------|-----|-----------|------------|
|
||||
| `npm start` | ❌ | ✅ | Entwicklung (schnell) |
|
||||
| `npm run dev:ssr` | ✅ | ✅ | Entwicklung mit SSR |
|
||||
| `npm run build:ssr` | ✅ Build | ❌ | Production Build erstellen |
|
||||
| `npm run serve:ssr` | ✅ | ❌ | Production Server starten |
|
||||
|
||||
---
|
||||
|
||||
## Nächste Schritte
|
||||
|
||||
1. Für normale Entwicklung: **`npm start`** verwenden
|
||||
2. Vor Production-Deployment: **`npm run build:ssr`** testen
|
||||
3. SSR-Funktionalität prüfen (siehe "Schritt 4: Testen")
|
||||
4. Bei Problemen: Logs prüfen und obige Lösungen durchgehen
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
Bei weiteren Problemen:
|
||||
|
||||
1. **Logs prüfen:** `npm run serve:ssr` zeigt Fehler in der Konsole
|
||||
2. **Browser DevTools:** Console + Network Tab
|
||||
3. **Build-Output:** `npm run build:ssr` zeigt Build-Fehler
|
||||
4. **Node-Version:** `node --version` (sollte ≥ v18 sein)
|
||||
Reference in New Issue
Block a user