289 lines
15 KiB
Markdown
289 lines
15 KiB
Markdown
# Bundle-Budgets per-Route mit PR-Comment-Visualisierung
|
|
|
|
**Status:** completed
|
|
**Task-ID:** #71
|
|
**Phase:** 10
|
|
**Estimated Effort:** 3-4 Tage Initial-Setup
|
|
**Owner:** unassigned
|
|
|
|
## Problem
|
|
|
|
`scripts/verify-bundle-size.mjs` enforced ein globales Bundle-Limit, aber:
|
|
|
|
- **Keine per-Route-Limits**: Dashboard-Route schleicht still über 500 KB ohne jemanden zu alarmieren; KB-Article-Route kann mit 50 KB auskommen, aber Limit ist als „Mittelwert" konfiguriert
|
|
- **Hartes Fail bei Überschreitung**: Build bricht, PR steckt — kein gradueller Warning-Pfad
|
|
- **Keine Visualisierung**: Reviewer sehen die tatsächlichen Per-Route-Bundle-Sizes nicht im PR; Debugging „warum ist Bundle gewachsen?" erfordert lokales Tooling
|
|
- **Keine Trend-Analyse**: Bundle-Growth über die Zeit unsichtbar — Audit-Findings „Bundle ist in den letzten 3 Monaten um 40 % gewachsen" werden zu spät bemerkt
|
|
- **Manual-Bundle-Visualizer fehlt**: Entwickler haben kein einfaches Tool um lokale Bundle-Composition zu inspizieren
|
|
|
|
Betroffene Codestellen:
|
|
- `scripts/verify-bundle-size.mjs` — bestehende Script
|
|
- `scripts/verify-bundle-size.test.mjs` — bestehende Tests
|
|
- `apps/web/vite.config.ts` — Build-Config
|
|
- `.github/workflows/ci.yml` + `.gitea/workflows/ci.yml` — CI-Integration
|
|
|
|
## Depends on
|
|
|
|
- `01-tech-debt-foundation/dep-updates.md` — Vite + rollup-plugin-visualizer aktuell
|
|
- Empfehlenswert (nicht hart): `10-compliance-polish/lighthouse.md` — manualChunks-Splitting wird dort etabliert, hier wird die Budget-Verifikation darauf angewendet
|
|
|
|
## Blocks
|
|
|
|
Keine harten Blocks.
|
|
|
|
## Approach
|
|
|
|
**Vier koordinierte Sub-Komponenten:**
|
|
|
|
### (a) Per-Route-Bundle-Limits in `scripts/verify-bundle-size.mjs`
|
|
|
|
Config-File `scripts/bundle-budgets.json`:
|
|
|
|
```json
|
|
{
|
|
"default": { "limitKb": 200, "warningKb": 180 },
|
|
"routes": {
|
|
"app/$tenant/dashboard": { "limitKb": 250, "warningKb": 225 },
|
|
"app/$tenant/crm": { "limitKb": 250, "warningKb": 225 },
|
|
"app/$tenant/crm/contacts": { "limitKb": 200, "warningKb": 180 },
|
|
"app/$tenant/settings/members": { "limitKb": 220, "warningKb": 200 },
|
|
"app/$tenant/settings/billing": { "limitKb": 220, "warningKb": 200 },
|
|
"app/$tenant/email-marketing": { "limitKb": 280, "warningKb": 250 },
|
|
"kb/$slug": { "limitKb": 150, "warningKb": 135 },
|
|
"auth/login": { "limitKb": 100, "warningKb": 90 },
|
|
"auth/register": { "limitKb": 100, "warningKb": 90 },
|
|
"auth/magic-link": { "limitKb": 80, "warningKb": 75 },
|
|
"admin/dashboard": { "limitKb": 220, "warningKb": 200 },
|
|
"admin/analytics": { "limitKb": 300, "warningKb": 275 },
|
|
"/": { "limitKb": 180, "warningKb": 160 }
|
|
},
|
|
"vendorChunks": {
|
|
"vendor-misc": { "limitKb": 300, "warningKb": 280 },
|
|
"vendor-recharts": { "limitKb": 200, "warningKb": 180 },
|
|
"vendor-react-email": { "limitKb": 150, "warningKb": 135 }
|
|
}
|
|
}
|
|
```
|
|
|
|
Sizes gemessen in **gzip-bytes** (nicht raw — gzip ist transport-relevant).
|
|
|
|
Script-Logik:
|
|
- Iteriere über alle gebauten Route-Files (`dist/client/assets/route-*.js`)
|
|
- Map Route-File-Name → Route-Pattern aus React-Router-v7-Manifest
|
|
- Wende Per-Route-Limit aus Config an; fallback zu Default
|
|
- Bei Warning-Überschreitung: yellow Output, kein Build-Bruch
|
|
- Bei Limit-Überschreitung: red Output, **Warning (nicht Fail)** in CI — PR-Comment statt Block
|
|
- Vendor-Chunks separat behandelt mit eigenem Limit-Set
|
|
|
|
### (b) PR-Comment-Output
|
|
|
|
CI-Job postet PR-Comment mit Markdown-Tabelle:
|
|
|
|
```
|
|
| Route | Size (gzip) | Limit | Status | Δ from main |
|
|
|---|---|---|---|---|
|
|
| app/$tenant/dashboard | 248 KB | 250 KB | ✅ | +12 KB |
|
|
| app/$tenant/crm | 261 KB | 250 KB | ⚠️ exceeds | +4 KB |
|
|
| auth/login | 87 KB | 100 KB | ✅ | -3 KB |
|
|
| vendor-recharts | 195 KB | 200 KB | ✅ | 0 KB |
|
|
```
|
|
|
|
- Mit `actions/github-script` oder Gitea-equivalent
|
|
- Comment wird upsert: Update statt Append (sucht existing Comment via Marker `<!-- bundle-budget-report -->`)
|
|
- Bei `main`-Vergleich: lade letztes `main`-Build-Manifest (CI-Artifact) und vergleiche
|
|
|
|
### (c) Vite-Bundle-Visualizer als Dev-Command
|
|
|
|
`packages.json` Script `bundle:visualize`:
|
|
|
|
```json
|
|
"bundle:visualize": "vite build --mode analyze && open dist/stats.html"
|
|
```
|
|
|
|
`apps/web/vite.config.ts`:
|
|
|
|
```ts
|
|
plugins: [
|
|
// ...
|
|
...(process.env.NODE_ENV === 'analyze' ? [
|
|
visualizer({ filename: 'dist/stats.html', open: false, gzipSize: true, brotliSize: true })
|
|
] : [])
|
|
]
|
|
```
|
|
|
|
`rollup-plugin-visualizer` als Dev-Dep.
|
|
|
|
Entwickler-Workflow: `pnpm bundle:visualize` → öffnet Treemap im Browser → identifiziert große Module → optimiert.
|
|
|
|
### (d) Vite-Config-Tweaks für besseres Splitting
|
|
|
|
Koordiniert mit `lighthouse.md` Step 4:
|
|
|
|
```ts
|
|
build: {
|
|
rollupOptions: {
|
|
output: {
|
|
manualChunks(id) {
|
|
if (id.includes('node_modules')) {
|
|
if (id.includes('lodash')) return 'vendor-lodash';
|
|
if (id.includes('date-fns')) return 'vendor-date-fns';
|
|
if (id.includes('recharts')) return 'vendor-recharts';
|
|
if (id.includes('@sentry')) return 'vendor-sentry';
|
|
if (id.includes('@react-email')) return 'vendor-react-email';
|
|
if (id.includes('react-pdf') || id.includes('pdfkit')) return 'vendor-pdf';
|
|
return 'vendor-misc';
|
|
}
|
|
}
|
|
}
|
|
},
|
|
chunkSizeWarningLimit: 200, // KB raw — Vite-internal warning, ergänzt unsere Budget-Checks
|
|
}
|
|
```
|
|
|
|
Dynamic-Imports für nicht-kritische Module (siehe `lighthouse.md` Step 4).
|
|
|
|
### (e) Dokumentation
|
|
|
|
- `docs/performance/bundle-budgets.md`:
|
|
- Wie Bundle-Budgets funktionieren
|
|
- Wie Per-Route-Limits konfiguriert werden
|
|
- Wie PR-Comment-Output gelesen wird
|
|
- Lokaler Visualizer-Workflow
|
|
- Anti-Patterns (Don't lazy-load critical-path, Don't bundle-split shared deps)
|
|
- Bewusste Exceptions (welche Routes haben höhere Limits und warum)
|
|
|
|
**Warum nicht Alternativen:**
|
|
- ❌ **Hartes Fail bei Überschreitung**: blockiert PRs für legitime Feature-Adds; Warning-Comment-Approach ist Sichtbarkeits-getrieben statt Block-getrieben
|
|
- ❌ **Globales Limit**: Routes haben unterschiedliche Komplexität — globales Limit ist immer falsch (zu lax für Auth, zu strict für Dashboard)
|
|
- ❌ **Webpack-Bundle-Analyzer**: Vite-Bundle-Visualizer (`rollup-plugin-visualizer`) ist Vite-native
|
|
- ❌ **Size-Limit Library**: gut für simple Cases, aber keine Per-Route-Logik out-of-the-box; Custom-Script ist flexibler
|
|
|
|
## Implementation Steps
|
|
|
|
1. **`bundle-budgets.json` Config-File**
|
|
- Files: `scripts/bundle-budgets.json`, `scripts/bundle-budgets.schema.json` (JSON-Schema für Validation)
|
|
- Initial-Werte aus aktuellem Build-Snapshot ableiten (current sizes + 10 % Headroom)
|
|
- Commit: `10-compliance-polish/bundle-budget: add per-route budget config`
|
|
|
|
2. **`verify-bundle-size.mjs` erweitern**
|
|
- Files: `scripts/verify-bundle-size.mjs`, `scripts/verify-bundle-size.test.mjs`
|
|
- Per-Route-Limit-Lookup, gzip-Size-Berechnung, Warning vs Fail-Behavior
|
|
- React-Router-v7-Manifest-Parsing für Route-File-Mapping
|
|
- Tests: Per-Route-Limit-Match, Default-Fallback, Vendor-Chunk-Limit, Warning vs Error
|
|
- Commit: `10-compliance-polish/bundle-budget: extend verify script with per-route limits`
|
|
|
|
3. **Vite-Config-manualChunks + Visualizer-Plugin**
|
|
- Files: `apps/web/vite.config.ts`, `apps/web/package.json`
|
|
- manualChunks pro Vendor-Library; visualizer-Plugin nur im `analyze`-Mode
|
|
- `bundle:visualize`-Script
|
|
- Commit: `10-compliance-polish/bundle-budget: split vendor chunks and add bundle visualizer`
|
|
|
|
4. **CI-PR-Comment-Action (GitHub)**
|
|
- Files: `.github/workflows/bundle-budget.yml`
|
|
- Job läuft nach `build`-Job, lädt vorheriges `main`-Manifest, postet PR-Comment via `actions/github-script`
|
|
- Marker `<!-- bundle-budget-report -->` für Upsert
|
|
- Commit: `10-compliance-polish/bundle-budget: add github workflow with pr comment`
|
|
|
|
5. **CI-PR-Comment-Action (Gitea)**
|
|
- Files: `.gitea/workflows/bundle-budget.yml`
|
|
- Gitea-API-Call statt `actions/github-script`; Comment-Upsert via Marker
|
|
- Commit: `10-compliance-polish/bundle-budget: add gitea workflow with pr comment`
|
|
|
|
6. **Main-Build-Manifest-Artifact-Persistence**
|
|
- Files: `.github/workflows/main-bundle-baseline.yml`, `.gitea/workflows/main-bundle-baseline.yml`
|
|
- Auf `main`-Push: Bundle-Manifest als Artifact uploaden mit Tag `main-baseline-<sha>`
|
|
- PR-Workflow lädt das letzte Artifact für Δ-Vergleich
|
|
- Commit: `10-compliance-polish/bundle-budget: persist main bundle baseline as ci artifact`
|
|
|
|
7. **Dokumentation**
|
|
- Files: `docs/performance/bundle-budgets.md`
|
|
- Workflow-Beschreibung, Config-Format, PR-Comment-Output-Erklärung, Visualizer-Anleitung
|
|
- Commit: `10-compliance-polish/bundle-budget: document bundle budget workflow`
|
|
|
|
## Test Requirements
|
|
|
|
- **Unit-Tests** (`verify-bundle-size.test.mjs`):
|
|
- Per-Route-Limit-Lookup: Route gefunden → korrektes Limit
|
|
- Default-Fallback: Route nicht in Config → default-Limit
|
|
- Vendor-Chunk-Match: Vendor-Chunk-Name → vendor-Limit
|
|
- Gzip-Size-Berechnung: bekannter Input → erwartete Size
|
|
- Warning-Behavior: Size im Warning-Range → yellow Output, exit code 0
|
|
- Error-Behavior: Size > Limit → red Output, **exit code 0** (kein Block, nur Warning), aber Report-Flag setzen
|
|
- **Integration-Test:**
|
|
- End-to-End: `pnpm build && node scripts/verify-bundle-size.mjs` → korrekter Output für aktuelles Build
|
|
- **CI-Workflow-Test:** Test-PR pushen → PR-Comment erscheint mit Bundle-Tabelle; zweiter Push → Comment wird upsert (nicht dupliziert)
|
|
- **Bundle-Visualizer-Test:** `NODE_ENV=analyze pnpm build` → `dist/stats.html` existiert und ist valide HTML
|
|
- **Coverage-Target:** ≥ 90 % im `verify-bundle-size.mjs` (kritischer Quality-Gate-Code)
|
|
- **Test-Files:** `scripts/verify-bundle-size.test.mjs` (extended)
|
|
|
|
**NICHT als completed markieren bevor PR-Comment auf einem Test-PR erscheint und korrekte Sizes anzeigt.**
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `scripts/bundle-budgets.json` enthält Per-Route-Limits für mind. 12 Routes + Vendor-Chunks
|
|
- [ ] `verify-bundle-size.mjs` erweitert um Per-Route-Logik; Tests grün
|
|
- [ ] Vite-manualChunks splittet Vendor-Bundles
|
|
- [ ] `pnpm bundle:visualize` öffnet Treemap im Browser
|
|
- [ ] GitHub-Workflow postet PR-Comment mit Bundle-Tabelle + Δ-Vergleich gegen main
|
|
- [ ] Gitea-Workflow ebenso
|
|
- [ ] Main-Bundle-Baseline wird als CI-Artifact persistiert
|
|
- [ ] Warning-Mode: bei Überschreitung kein PR-Block, aber sichtbarer Comment
|
|
- [ ] Coverage ≥ 90 % in `verify-bundle-size.mjs`
|
|
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
|
|
- [ ] `docs/performance/bundle-budgets.md` angelegt
|
|
- [ ] Detail-MD Progress Log aktualisiert
|
|
- [ ] PROGRESS.md Status auf `completed`
|
|
|
|
## Rollback Strategy
|
|
|
|
- **Bundle-Budgets zu strict**: Limits in `bundle-budgets.json` lockern via Commit; kein Code-Rollback nötig
|
|
- **PR-Comment-Workflow brokens PR-Flow**: Workflow-File auf `if: false` setzen via Commit → Comment-Posting deaktiviert
|
|
- **manualChunks-Config bricht App**: Vite-Config-Commit reverten; default-Splitting funktioniert
|
|
- **Visualizer-Plugin erhöht Build-Time** zu stark: `analyze`-Mode-Gate entfernt visualizer aus Default-Build → keine Auswirkung
|
|
- **CI-Artifact-Storage voll**: Artifact-Retention-Policy (7 Tage) konfigurieren
|
|
|
|
## Security Notes
|
|
|
|
- **Bundle-Budgets enthalten keine Secrets**: Config ist Public-Code
|
|
- **PR-Comment-Token**: GitHub-Token braucht `pull-requests: write`-Scope (minimal); Gitea-Equivalent
|
|
- **Bundle-Visualizer-Output (`stats.html`)**: enthält Source-Maps-Referenzen → niemals als Public-Artifact deployen, nur lokal/Artifact-Storage
|
|
- **Main-Bundle-Baseline-Artifact**: enthält Datei-Namen und Sizes, keine Source-Maps → unbedenklich
|
|
|
|
## Subagent Recommendations
|
|
|
|
- **Planning:** `Plan`-Subagent mit dieser Detail-MD + existierendem `verify-bundle-size.mjs` als Input — soll Per-Route-Config-Schema validieren
|
|
- **Research:** `Explore`-Subagent mit Auftrag „lauf `pnpm build` lokal und liste Sizes pro Route-File aus `dist/client/assets/`; schlage Initial-Limits vor (current + 10 %)"
|
|
- **Implementation:** Ein `general-purpose`-Subagent pro Implementation-Step (1-7), parallel-fähig (außer 4/5 die nach 1-3 sequenziell)
|
|
- **Tests:** Test-Code direkt mit Implementation in Step 2 + Workflow-Tests in Step 4/5
|
|
- **Verification:** `gsd-verifier` für Acceptance-Criteria; PR-Comment-Verifikation auf Test-PR
|
|
- **Code-Review:** `gsd-code-reviewer` nach Step 7, Fokus auf Script-Robustness (Edge-Cases bei manualChunks-Renames, Manifest-Parsing-Fehler)
|
|
|
|
## Staging-Deployment-Steps
|
|
|
|
Dieser Task hat keine Staging-Komponenten — alles läuft in CI gegen Build-Artifacts. Aber:
|
|
|
|
1. Branch `agent/10-bundle-budget` pushen
|
|
2. PR öffnen → GitHub-Workflow läuft → PR-Comment erscheint mit Bundle-Tabelle
|
|
3. **Visualisierung-Verifikation lokal**: `pnpm bundle:visualize` → Treemap zeigt Vendor-Chunks-Split korrekt
|
|
4. **Main-Baseline-Verifikation**: nach Merge zu `main` → Workflow lädt Manifest als Artifact → nächster PR zeigt Δ-Vergleich
|
|
5. **Warning-Test**: künstlich großen Import in einen Route-File einbauen → PR-Comment zeigt Warning-Status für diese Route
|
|
|
|
## Deviations from Plan
|
|
|
|
- **No separate `manualChunks` change.** The Vite config already implements vendor-chunk splitting via `apps/web/app/utils/build/manualChunks.ts` (vendor-react, vendor-charts, vendor-ai-sdk, vendor-editor-tiptap, vendor-editor-prosemirror, vendor-markdown, vendor-monaco, vendor-pdf, vendor-workflow, vendor-core-utils). Implementation Step (d) of the spec was a no-op — the budgets reference those existing chunk names.
|
|
- **Baseline download in Gitea is opt-in via `BUNDLE_BASELINE_URL`.** Gitea Actions artifact-download isn't a first-class action in this repo's runner image, so the workflow uses a curl-fetched URL if the operator configures one and otherwise renders the PR comment with Δ-from-main as `—`. GitHub uses `dawidd6/action-download-artifact` for the same purpose.
|
|
- **`chunkSizeWarningLimit` left at 1800.** The spec suggested tightening to 200 KB, but the existing config intentionally keeps Rollup quiet so our own gates control the noise. Lowering would surface raw-byte warnings for chunks that are already within our gzip budgets.
|
|
|
|
## Progress Log
|
|
|
|
- 2026-05-17 16:38 — `a0e2c1c9` — add bundle-budgets json config with per-route limits (15 routes + 12 vendor chunks)
|
|
- 2026-05-17 16:43 — `b618eea2` — extend verify-bundle-size with per-route enforcement (gzip-size + status taxonomy + --json / --per-route-only flags; 30 unit tests pass)
|
|
- 2026-05-17 16:45 — `8d2050e7` — integrate rollup-plugin-visualizer as ANALYZE_BUNDLE=true opt-in; preserves Sentry + asset-CDN base
|
|
- 2026-05-17 16:46 — `7fbfcab4` — add GitHub + Gitea PR-comment workflows, baseline workflow, renderer + Gitea upserter; 12 renderer tests pass
|
|
- 2026-05-17 16:47 — `c4374eb8` — add `docs/architecture/bundle-budgets.md`
|
|
|
|
## Lessons Learned
|
|
|
|
- React Router v7 build emits both client and server passes via a single `pnpm build`; the visualizer plugin's default `closeBundle` hook fires once per pass. For multi-pass builds, prefer `emitFile: false` + an absolute `filename` so the treemap lands deterministically in `apps/web/build/`.
|
|
- The existing group-budget gate in `verify-bundle-size.mjs` already covers regressions in initial-payload size. The per-route budget layer is purely visibility/communication — non-blocking is the right default.
|