Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/10-compliance-polish/bundle-budget.md
T

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

{
  "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:

"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

  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.