276 lines
6.1 KiB
Markdown
276 lines
6.1 KiB
Markdown
# 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)
|