15 KiB
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 Scriptscripts/verify-bundle-size.test.mjs— bestehende Testsapps/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:
{
"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-scriptoder Gitea-equivalent - Comment wird upsert: Update statt Append (sucht existing Comment via Marker
<!-- bundle-budget-report -->) - Bei
main-Vergleich: lade letztesmain-Build-Manifest (CI-Artifact) und vergleiche
(c) Vite-Bundle-Visualizer als Dev-Command
packages.json Script bundle:visualize:
"bundle:visualize": "vite build --mode analyze && open dist/stats.html"
apps/web/vite.config.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:
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
-
bundle-budgets.jsonConfig-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
- Files:
-
verify-bundle-size.mjserweitern- 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
- Files:
-
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
- Files:
-
CI-PR-Comment-Action (GitHub)
- Files:
.github/workflows/bundle-budget.yml - Job läuft nach
build-Job, lädt vorherigesmain-Manifest, postet PR-Comment viaactions/github-script - Marker
<!-- bundle-budget-report -->für Upsert - Commit:
10-compliance-polish/bundle-budget: add github workflow with pr comment
- Files:
-
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
- Files:
-
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 Tagmain-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
- Files:
-
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
- Files:
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
- End-to-End:
- 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.htmlexistiert 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.jsonenthält Per-Route-Limits für mind. 12 Routes + Vendor-Chunksverify-bundle-size.mjserweitert 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 testgründocs/performance/bundle-budgets.mdangelegt- Detail-MD Progress Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
- Bundle-Budgets zu strict: Limits in
bundle-budgets.jsonlockern via Commit; kein Code-Rollback nötig - PR-Comment-Workflow brokens PR-Flow: Workflow-File auf
if: falsesetzen 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 + existierendemverify-bundle-size.mjsals Input — soll Per-Route-Config-Schema validieren - Research:
Explore-Subagent mit Auftrag „laufpnpm buildlokal und liste Sizes pro Route-File ausdist/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-verifierfür Acceptance-Criteria; PR-Comment-Verifikation auf Test-PR - Code-Review:
gsd-code-reviewernach 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:
- Branch
agent/10-bundle-budgetpushen - PR öffnen → GitHub-Workflow läuft → PR-Comment erscheint mit Bundle-Tabelle
- Visualisierung-Verifikation lokal:
pnpm bundle:visualize→ Treemap zeigt Vendor-Chunks-Split korrekt - Main-Baseline-Verifikation: nach Merge zu
main→ Workflow lädt Manifest als Artifact → nächster PR zeigt Δ-Vergleich - 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
manualChunkschange. The Vite config already implements vendor-chunk splitting viaapps/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 usesdawidd6/action-download-artifactfor the same purpose. chunkSizeWarningLimitleft 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— adddocs/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 defaultcloseBundlehook fires once per pass. For multi-pass builds, preferemitFile: false+ an absolutefilenameso the treemap lands deterministically inapps/web/build/. - The existing group-budget gate in
verify-bundle-size.mjsalready covers regressions in initial-payload size. The per-route budget layer is purely visibility/communication — non-blocking is the right default.