matthias.lotz
58a1979b89
- Add .github/ISSUES/upgrade-deps-react-node-20251028.md with analysis summary - Add docs/UPGRADE_PLAN-upgrade-deps-react-node-20251028.md with detailed plan and steps Branch: upgrade/deps-react-node-20251028
150 lines
4.2 KiB
Markdown
150 lines
4.2 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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):
|
||
|
||
```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)
|