> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Performance baseline and budgets

> Status: Active Owner: Platform Architecture Related: ADR-008 (Vite SPA), TURBOREPO_USAGE.md, MICROFRONTENDS_RUNBOOK.md

**Status:** Active\
**Owner:** Platform Architecture\
**Related:** [ADR-008](../architecture/decisions/ADR-008-vite-spa-vs-ssr.md) (Vite SPA), [TURBOREPO\_USAGE.md](./TURBOREPO_USAGE.md), [MICROFRONTENDS\_RUNBOOK.md](./MICROFRONTENDS_RUNBOOK.md)

This document operationalizes the **Performance Architecture** plan: measure before changing runtime topology (microfrontends count, framework migrations), and keep Vite/Rolldown + Turborepo as the primary levers.

## 1. What to baseline

| Signal                      | Tool / artifact                                                                                   | When                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Repo + pipeline timing      | `npm run perf:baseline` or `perf:baseline:quick`                                                  | Monthly or before large refactors                 |
| JS chunk sizes (post-build) | `npm run perf:build-metrics` (also embedded in `perf:baseline` when `dist/` exists)               | After dependency upgrades or vendor chunk changes |
| Bundle graph                | `npm run build:analyze` → `dist/stats.html`                                                       | When investigating regressions                    |
| Runtime Web Vitals          | Vercel Speed Insights (production); Lighthouse locally                                            | Before/after microfrontend activation             |
| PWA precache                | DevTools → Application → Service Workers + cache storage; `vite.config.ts` Workbox `globPatterns` | After PWA or routing changes                      |

## 2. Commands

```bash theme={null}
npm run build
npm run perf:build-metrics          # human-readable table + reports/perf/build-chunks-YYYY-MM-DD.json
npm run perf:build-metrics:json     # stdout JSON only

npm run perf:baseline               # structural + timed dev metrics → reports/perf/baseline-*.md
npm run perf:baseline:structural    # fast structural only (includes dist chunk rows if dist/ exists)

npm run perf:budgets:check          # fail if precache-critical JS chunks exceed budget (needs dist/)
VITE_BUDGETS_WARN_ONLY=1 npm run perf:budgets:check   # log violations, exit 0 (CI informational)
```

Budget defaults match Workbox `maximumFileSizeToCacheInBytes` (2 MiB) for the four precache-critical entry patterns (`index-*`, `vendor-react-*`, `vendor-radix-*`, `vendor-supabase-*`). Override with `VITE_BUDGET_CRITICAL_CHUNK_BYTES`.

## 3. Route timing (manual)

There is no single automated “route timing” suite in-repo today. For critical flows (login, dashboard, heavy tables, PDF export):

1. Chrome DevTools → Performance → record navigation.
2. Or Playwright trace + `performance` marks where needed.

Record dates and rough LCP/TTI in PR descriptions when claiming perf wins.

## 4. Microfrontends

Path-based splits are **deployment** concerns; they do not replace bundle discipline. Before activating Phase 3:

* Follow [MICROFRONTENDS\_ACTIVATION\_CHECKLIST.md](./MICROFRONTENDS_ACTIVATION_CHECKLIST.md).
* Re-baseline Web Vitals on preview (runbook soak).

## 5. Turborepo

Turborepo improves **CI and local task** latency, not browser JS size. See [TURBOREPO\_USAGE.md](./TURBOREPO_USAGE.md) for remote cache setup and cache-hit diagnostics.

## See also

* `scripts/perf/capture-baseline.ts`
* `scripts/perf/report-build-chunks.ts`
* `scripts/perf/check-vite-budgets.ts`
* [ADR-019](../architecture/decisions/ADR-019-nextjs-turbopack-deferral.md) — Next.js / Turbopack deferral