bizmatch-project/bizmatch/SSR_ANLEITUNG.md

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

# 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)

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!

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!

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:

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:

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:

# 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

# 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

rm -rf node_modules package-lock.json
npm install

Problem 3: Error: EADDRINUSE: address already in use :::4200

Lösung: Port ist bereits belegt

# 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

# 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:

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):

# 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)