Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,288 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user