# Upgrade-Plan: React, Router, MUI, Node (upgrade/deps-react-node-20251028)

**Status:** ✅ **ABGESCHLOSSEN** (28.–29. Oktober 2025)  
**Branch:** `upgrade/deps-react-node-20251028`

## Zusammenfassung

Alle vier Phasen erfolgreich durchgeführt:
- ✅ Phase 1: Backend Node 14 → 24 
- ✅ Phase 2: Frontend React 17 → 18.3.1, react-scripts 5.0.1
- ✅ Phase 3: React Router v5 → v6.30.1
- ✅ Phase 4: MUI v4 → v5.14.0 (mit sx-Migration)

**Zusätzliche Arbeiten:**
- Entfernung von `@mui/styles` und `--legacy-peer-deps`
- Ersatz von `react-lottie` durch `lottie-react`
- ESLint-Bereinigung
- Dev-Umgebung mit HMR (`Dockerfile.dev` + `docker-compose.override.yml`)

**Ergebnisse:**
- Alle Container laufen stabil
- Production Builds kompilieren sauber
- Dev-Server mit Live-Reload funktioniert
- Alle Router-Routen funktionieren
- UI/UX unverändert

---

## Ziel

Schrittweise und rückfallfähige Aktualisierung der Laufzeit und Frameworks:

- Backend: Node 14 -> Node 24 ✅
- Frontend: React 17 -> React 18, react-scripts 4 -> 5 ✅
- React Router: v5 -> v6 ✅
- MUI: v4 -> v5 (mit sx-Migration) ✅

## Umfang

- Änderungen an `backend/Dockerfile` für Node-Version
- Aktualisierung `frontend/package.json` (react/react-dom/react-scripts)
- CI / Produktions-Build-Pipeline (Dockerfile, prod.sh) Smoke-tests
- Code-Änderungen: Router-Hooks (useHistory → useNavigate), App.js (Switch → Routes), evtl. MUI-Imports

## Tatsächlicher Ablauf und Zeitaufwand

### Phase 0 — Vorbereitung ✅
- Branch erstellt: `upgrade/deps-react-node-20251028`
- Issue/PR Templates generiert
- Backup-Commits vorbereitet

### Phase 1 — Node runtime bump ✅ (Dauer: ~1h)

**Durchgeführt:**
1. ✅ `backend/Dockerfile`: `FROM node:14` → `FROM node:24`
2. ✅ Docker Build & Container-Start erfolgreich
3. ✅ SQLite DB initialisiert, Backend läuft auf Port 5000
4. ✅ Commit: `acdb2fa` "chore(backend): upgrade to Node 24"

**Ergebnis:** Backend läuft stabil unter Node 24.

---

### Phase 2 — React 18 & react-scripts 5 ✅ (Dauer: ~6h)

**Durchgeführt:**
1. ✅ `frontend/package.json` aktualisiert:
   - `react` & `react-dom` → `^18.3.1`
   - `react-scripts` → `5.0.1`
2. ✅ `frontend/src/index.js`: Migration zu `createRoot()` API
3. ✅ `npm install` und `npm run build` erfolgreich
4. ✅ Docker production build erfolgreich
5. ✅ Commit: `9353458` "chore(frontend): upgrade React to 18.3.1 and migrate to createRoot API"

**Ergebnis:** React 18 läuft, Production Build kompiliert sauber.

---

### Phase 3 — Router v5 → v6 ✅ (Dauer: ~4h)

**Durchgeführt:**
1. ✅ `react-router-dom` → `^6.28.0` (installed `6.30.1`)
2. ✅ Code-Änderungen:
   - `<Switch>` → `<Routes>`
   - `<Route component={...}>` → `<Route element={<.../>}>`
   - `useHistory()` → `useNavigate()`
   - Pfad-Anpassungen für nested routes
3. ✅ Alle Routen funktionieren (Upload, Groups, Moderation, Slideshow, 404)
4. ✅ Commit: `5ba4634` "chore(frontend): migrate react-router-dom v5 to v6"

**Ergebnis:** Navigation funktioniert vollständig mit Router v6.

---

### Phase 4 — MUI v4 → v5 ✅ (Dauer: ~12h)

**Durchgeführt:**
1. ✅ Packages installiert:
   - `@mui/material@^5.14.0`
   - `@mui/icons-material@^5.14.0`
   - `@emotion/react@^11.11.0`
   - `@emotion/styled@^11.11.0`
2. ✅ Imports migriert: `@material-ui/*` → `@mui/*`
3. ✅ Komponenten auf `sx` migriert:
   - `UploadProgress.js` (Commit: `8535e8f`)
   - `DescriptionInput.js` (Commit: `4aac9da`)
   - `MultiImageDropzone.js` (Commit: `494c09e`)
   - `MultiUploadPage.js` (Commit: `182dcb2`)
   - `SlideshowPage.js` (Commit: `5b4855a`)
   - `GroupsOverviewPage.js` und weitere
4. ✅ `@mui/styles` vollständig entfernt (Commit: `a44a85b`)
5. ✅ ESLint-Fixes durchgeführt (Commit: `bf11545`)

**Ergebnis:** Alle Komponenten nutzen MUI v5 mit `sx`-Styling, keine Legacy-Pakete mehr.

---

### Zusätzliche Arbeiten ✅

#### Dependency Cleanup
- ✅ `react-lottie` → `lottie-react` (Commit: `a44a85b`)
  - Peer-Dependency-Konflikt behoben
  - `Loading.js` Component aktualisiert
- ✅ `--legacy-peer-deps` aus `frontend/Dockerfile` entfernt
- ✅ Clean `npm install` ohne Flags

#### Dev-Umgebung
- ✅ `frontend/Dockerfile.dev` erstellt (Node 18, CRA dev server + nginx)
- ✅ `docker-compose.override.yml` für Dev-Overlay
  - Frontend: http://localhost:3000 (mit HMR)
  - Backend: http://localhost:5000 (mit nodemon)
  - Bind-Mounts für Live-Editing
  - Separate `node_modules` Volumes
- ✅ Dev-Container kompiliert erfolgreich (react-router-dom@6.30.1)

#### Maintenance
- ✅ Browserslist DB aktualisiert (1.0.30001751)
- ✅ PostCSS Deprecation-Warnung dokumentiert (harmlos, von react-scripts)

---

## Aufwandsschätzung vs. Tatsächlich

| Phase | Geschätzt | Tatsächlich |
|-------|-----------|-------------|
| Phase 1 (Node) | 0.5–2h | ~1h ✅ |
| Phase 2 (React 18) | 4–12h | ~6h ✅ |
| Phase 3 (Router v6) | 2–6h | ~4h ✅ |
| Phase 4 (MUI v5) | 24–56h | ~12h ✅ |
| Dev-Umgebung | - | ~3h ✅ |
| Tests/Docs | 4–8h | ~2h ✅ |
| **Gesamt** | **3–10 Tage** | **~28h (3.5 Tage)** ✅ |

**Fazit:** Upgrade verlief deutlich schneller als konservativ geschätzt, dank strukturiertem Phasen-Ansatz.

---

## Hinweise für CI / Docker

- Wenn sqlite3 native gebaut werden muss, Dockerfile benötigt `build-essential` und `python` für node-gyp (oder alternativ use prebuilt binaries).
- Node LTS images: `node:18` oder `node:20` (prüfen, ob alle libs kompatibel)

## Beispiel Patches (starter)

- Backend Dockerfile (quick):

```diff
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@
- FROM node:14
+ FROM node:18
```

## Nächste Schritte (konkret für mich)

1. Erstelle PR mit Phase 1 (Node bump) + docs + TODO-Update
2. Nach Freigabe: PR für Phase 2 (React18)

---

Dateien in diesem PR/Branch:
- `.github/ISSUES/upgrade-deps-react-node-20251028.md` (Issue-Template)
- `docs/UPGRADE_PLAN-upgrade-deps-react-node-20251028.md` (dieses Dokument)