Project-Image-Uploader/docs/UPGRADE_PLAN-upgrade-deps-react-node-20251028.md

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

Datum: 2025-10-28 Branch: upgrade/deps-react-node-20251028

Ziel

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

• Backend: Node 14 -> Node 18 (LTS) (Schnellwin)
• Frontend: React 17 -> React 18, react-scripts 4 -> 5
• Optional (separat): react-router v5 -> v6
• Optional (iterativ): MUI v4 -> v5 (größere Refactor-Phase)

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

Schritte (detailliert)

Phase 0 — Vorbereitung (0.5–1h)

• Erstelle Branch (bereits erstellt)
• Sicherstellen, dass Tests/Build aktuell grün sind
• Erstelle Backup-Branch oder Tag

Phase 1 — Node runtime bump (0.5–2h) [Schnellwin]

Ziel: Backend in Node 18 betreiben

Aktionen:

1. Edit backend/Dockerfile: FROM node:14 → FROM node:18 (oder node:18-slim)
2. Locally: build & run container

docker build -t image-uploader-backend-test ./backend
docker run --rm -p 5000:5000 image-uploader-backend-test
# oder: docker compose -f docker-compose.yml up --build backend

3. Smoke-test: API Endpoints, DB, uploads
4. Falls native build-errors (sqlite3), ergänze build-essentials in Dockerfile

Akzeptanzkriterien:

• Backend container läuft unter Node 18 ohne runtime-exceptions

Phase 2 — React 18 & react-scripts 5 (4–12h)

Ziel: Frontend auf React 18 bringen (nicht MUI noch nicht zwangsläufig)

Aktionen:

1. Update frontend/package.json:

   • react & react-dom → ^18.2.0
   • react-scripts → ^5.0.1

2. Lokales Install & Build

cd frontend
npm ci
npm run build

3. Fix build-errors (häufig): PostCSS, Webpack-Optionen, kleine API-Änderungen
4. Test dev-mode (npm start) und important pages (upload, moderation, slideshow)

Akzeptanzkriterien:

• npm run build liefert statische Assets
• Dev server läuft, app funktioniert manuell

Phase 3 — Router v5 → v6 (2–6h)

Ziel: Modernisierung der Router-API

Aktionen:

1. Replace react-router-dom version in package.json → ^6.x
2. Code changes:
   • Switch → Routes + Route element={<Comp/>}
   • useHistory() → useNavigate()
   • withRouter entfernen
3. Sorgfältige manuelle Tests der Navigation

Akzeptanzkriterien:

• Navigation / Link-Verhalten wie zuvor, Unit/E2E tests grün

Phase 4 — MUI v4 → v5 (größerer Refactor) (2–5d)

Ziel: Migration zu MUI v5 mit modernem Styling (sx/styled)

Aktionen:

1. Upgrade Packages: @mui/material, @mui/icons-material
2. Entweder:
   • kurzfristig: @mui/styles (Kompatibilitäts-Paket) verwenden, um Zeit zu gewinnen; oder
   • langfristig: ersetze makeStyles/JSS mit sx oder styled
3. Theme/Spacing Anpassungen, Icons-Import prüfen
4. UI-Tests und visueller Abgleich

Akzeptanzkriterien:

• Komponenten rendern korrekt, Theme konsistent

Phase 5 — Tests & Production Build

1. Full Docker production build: ./prod.sh Option 4
2. E2E / manuelle smoke tests: Upload, Moderation, Slideshow

Aufwandsschätzung (grobe Orientierung)

• Phase 1 (Node bump): 0.5–2h
• Phase 2 (React 18): 4–12h
• Phase 3 (Router v6): 2–6h
• Phase 4 (MUI v5): 24–56h (je nach Umfang)
• Tests / CI / Docs: 4–8h

Gesamtschätzung (conservative): 3–10 Arbeitstage (abhängig von MUI scope)

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

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