EpicNext-Cms/docs/performance-budgets.md

Informational route JavaScript budgets

Run after the existing production build; no second build or server is needed:

node scripts/performance-report.mjs --next-dir .next --config scripts/performance-budgets.json --output-dir build-reports

The command writes report.json and report.md and prints the Markdown report. An optional PERFORMANCE_COMMIT_SHA environment variable records the commit declared by the build caller; the script does not infer that an existing build matches the current checkout. JSON also records BUILD_ID, Node/zlib versions, manifest provenance, exact file paths, sizes and source entries.

What is measured

For each configured App Router route, resolve its exact app path using app-path-routes-manifest.json and server/app-paths-manifest.json. Read its generated page_client-reference-manifest.js as a JSON assignment without executing JavaScript. Use its sibling page/build-manifest.json, falling back to the root build manifest only if that sibling is absent.

The initial entry envelope is the union of route bootstrap rootMainFilesTree[appPath] (or rootMainFiles) and every client chunk that route's client-reference manifest lists. This includes layout, page and boundary/loading entries.

The manifest exposes those chunks differently per bundler. Turbopack emits an explicit per-segment entryJSFiles map; webpack emits no such field and records chunks only per client module, as clientModules[*].chunks, in [chunkId, fileName, chunkId, fileName, …] order. The report reads entryJSFiles when present and otherwise derives the same envelope from clientModules, which is the source Next's own static-routes-info uses. Numeric chunk ids are skipped; a malformed chunk path still fails rather than being dropped, so a broken manifest cannot quietly under-report a route.

The build runs webpack (next build --webpack), so the clientModules path is the live one. An earlier revision only read entryJSFiles, and after the switch to webpack every route reported unavailable while the command still exited 0 — the budgets were silently not being measured. When a bundler switch changes the manifest layout again, re-check this section rather than trusting a clean exit.

The definition follows the data exposed by the installed Next 16.3.8 build and the getLinkAndScriptTags / getRequiredScripts renderer helpers; it is deliberately a build-artifact envelope, not a browser network trace. Conditional rendering, redirects, streaming and browser caches can change actual requests.

• Raw bytes are filesystem byte lengths of unique JavaScript assets in that envelope.
• Gzip bytes are the sum of independent gzip level 9 compressions of those files using the recorded Node/zlib runtime. They are not gzip of concatenated source, nor observed CDN transfer sizes.
• Deployment query strings and /_next/ prefixes are normalized before deduplication. Shared files count once per route; each route is measured independently, with no misleading cross-route total.
• Legacy nomodule polyfills are measured separately, outside the modern initial budget. CSS, source maps, images, external scripts, HTML/RSC payloads and async-only chunks absent from the manifest's chunk lists are excluded.
• This report makes no claims about execution cost, LCP, hydration time or real-user performance.

Initial limits

The first limits are baseline bytes × 1.15, rounded upward to the next 10 KiB (10,240 bytes) independently for raw and gzip. They are provisional size alerts, not validated speed targets. Baseline: local production build build-TfctsWXpff2fKS, Next 16.3.4 Turbopack; its source commit was not inferred.

The production build now runs webpack, so the numbers it reports are not directly comparable to the baseline below. Re-measured on the current webpack build the routes land at /me 786138/247738, /news 781601/245672, /events 782011/245923, /search 783262/246578, /admin/catalog 1172089/370843, /admin/studio/furni 1374128/440546 (raw/gzip). All remain inside the limits below, but /admin/studio/furni sits at ~98% of its gzip limit, so the next dependency added to that route will trip it. Recalibrate the table and scripts/performance-budgets.json together if the intent is to reset the baseline on webpack.

Route	Baseline raw bytes	Baseline gzip bytes	Raw limit	Gzip limit
/me	767156	238571	890880	276480
/news	765367	237599	880640	276480
/events	765851	237964	890880	276480
/search	765851	237964	890880	276480
/admin/catalog	1654898	492619	1904640	573440
/admin/studio/furni	1241312	391541	1433600	450560

Configured limits are positive integer bytes; null explicitly means observe-only. scripts/performance-budgets.json remains mode: informational. Exceeding a limit produces over-budget and a warning, with exit code 0. Missing production BUILD_ID, unsupported manifests, missing routes or missing referenced assets produce unavailable with a reason and no partial/zero total, also exit code 0. Malformed budget configuration or an unwritable output directory fails the command. This keeps initial CI reporting non-blocking while preventing invalid configuration from quietly disabling limits.

Synthetic tests cover shared-chunk deduplication, exact byte/gzip calculations, route bootstrap selection, missing data, safe parsing and CLI exit behavior. Run pnpm exec vitest run --coverage.enabled=false scripts/performance-report.test.mjs.