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