route-bundle-size 0.1.0 → 0.2.0

package/README.md

@@ -2,48 +2,194 @@
 
 Per-route first-load JS budget for Next.js Turbopack builds.
 
-It reads the route stats that `next build` writes, gzips each route's first-load chunks, and compares a PR build with its merge-base build. It fails when a route grows past the budget.
+Next.js 16 removed the per-route "First Load JS" column from the `next build` output ([vercel/next.js#83815](https://github.com/vercel/next.js/pull/83815)). Next.js 16.2 started writing `.next/diagnostics/route-bundle-stats.json` on Turbopack builds, and this tool turns that file into a per-route budget for CI.
+
+It reads the route stats, gzips each route's first-load chunks, and compares a PR build with its merge-base build. It fails when a route grows past the budget or is larger than its size limit.
 
 - Sizes are per route, first-load JS only.
 - The budget gates on gzip size by default. Raw bytes are also supported.
-- The [example workflow](#github-actions) uses the PR's merge base as the baseline, so later commits on the base branch never count against the PR.
+- The [GitHub Action](#github-actions) uses the PR's merge base as the baseline, so later commits on the base branch never count against the PR.
 
 ## Requirements
 
 - Next.js >= 16.2 with Turbopack. Turbopack is the default for `next build`.
 - Node.js >= 22.12.
 
-Next.js 16.2 and later writes `.next/diagnostics/route-bundle-stats.json` on every Turbopack production build. No flag or env var is needed. `next build --webpack` does not write this file, so webpack builds are not supported.
+The stats file is written on every Turbopack production build. No flag or env var is needed.
 
 ## Quick start
 
 ```bash
 # At the baseline commit
 npx next build
-npx route-bundle-size measure --app-dir . --out /tmp/baseline.json
+npx route-bundle-size measure --out /tmp/baseline.json
 
 # At the commit you want to check
 npx next build
-npx route-bundle-size measure --app-dir . --out /tmp/current.json
+npx route-bundle-size measure --out /tmp/current.json
 
 npx route-bundle-size diff --current /tmp/current.json --baseline /tmp/baseline.json
 ```
 
 In a monorepo, build the app and point `--app-dir` at it, for example `--app-dir apps/web`.
 
+## GitHub Actions
+
+The action builds the PR head and its merge base in one job, compares them, and writes the result to the job summary. It posts no PR comment and needs only `contents: read`, so it works for PRs from forks.
+
+```yaml
+name: Bundle size
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  bundle-size:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - uses: bra31k/route-bundle-size@v0
+```
+
+`fetch-depth: 0` is required, because the action needs the history to find the merge base. `ref` makes it build the PR head commit instead of the merge commit that GitHub creates.
+
+Inputs, all optional:
+
+- `app-dir`: the Next.js app directory. Default `.`.
+- `install-command`: installs the dependencies. Default `npm ci`.
+- `build-command`: builds the app. Default `npx next build`.
+- `base`: the git ref to compare with. Default `origin/<base branch of the PR>`. Set it for events that are not pull requests, such as `push`.
+- `package`: the npm spec of the CLI. Default: `route-bundle-size` at the action's own version.
+
+Output:
+
+- `report`: the path to the markdown report.
+
+The action resolves the merge base of `base` and the head. It installs, builds and measures the head. Then it checks out the merge base with `git checkout --force`, installs, builds and measures it, and returns to the head. It runs `diff --format markdown` at the head, so the PR's config file is used.
+
+Notes:
+
+- pnpm, yarn or bun: set up the package manager before `setup-node`, and set `install-command`, for example `pnpm install --frozen-lockfile`. Make the `cache:` value of `setup-node` match your lockfile, or remove it.
+- Monorepo: set `app-dir: apps/web`. Both commands run in `app-dir`, and the config file is read from there.
+- The cost is a second build in each PR run.
+- GitHub shows the job summary even when the step fails.
+- Pin `@v0`, which moves with each 0.x release, or an exact `@v0.2.0`.
+
+### Without the action
+
+For other CI systems or a custom setup, this workflow does the same steps by hand:
+
+```yaml
+name: Bundle size
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  bundle-size:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      ROUTE_BUNDLE_SIZE: route-bundle-size@0.2.0
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      # An empty sha would make "git checkout --detach" stay at HEAD,
+      # so both sides would measure the same build and always pass.
+      - name: Resolve merge base
+        id: merge_base
+        run: |
+          sha=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
+          if [ -z "$sha" ]; then
+            echo "::error::Could not resolve a merge base with origin/${{ github.base_ref }}."
+            exit 1
+          fi
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          echo "head=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build current
+        run: npx next build
+
+      - name: Measure current
+        run: npx --yes "$ROUTE_BUNDLE_SIZE" measure --out "$RUNNER_TEMP/current.json"
+
+      - name: Check out merge base
+        run: git checkout --force --detach ${{ steps.merge_base.outputs.sha }}
+
+      - name: Install dependencies at merge base
+        run: npm ci
+
+      - name: Build baseline
+        run: npx next build
+
+      - name: Return to PR head
+        run: git checkout --force --detach ${{ steps.merge_base.outputs.head }}
+
+      # .next is gitignored, so the baseline build survives the checkout.
+      # Running diff at the PR head uses the PR's config file.
+      - name: Measure baseline
+        run: npx --yes "$ROUTE_BUNDLE_SIZE" measure --out "$RUNNER_TEMP/baseline.json"
+
+      - name: Compare
+        run: |
+          npx --yes "$ROUTE_BUNDLE_SIZE" diff \
+            --current "$RUNNER_TEMP/current.json" \
+            --baseline "$RUNNER_TEMP/baseline.json" \
+            --format markdown
+```
+
+Notes:
+
+- The baseline is the merge base, not the tip of the base branch, so commits on the base branch that the PR does not contain never count against it.
+- Pin the tool version in one place, as `ROUTE_BUNDLE_SIZE` does here. Both snapshots are then made by the same version.
+- The tool runs through `npx`, so it does not need the project's `node_modules`. No reinstall is needed after returning to the PR head.
+- If the merge-base build fails, the job fails. It does not pass quietly.
+- On other CI systems `GITHUB_STEP_SUMMARY` is not set, so `--format markdown` prints the report to stdout.
+
 ## Commands
 
+`npx route-bundle-size --version` prints the installed version.
+
 ### `measure`
 
 ```bash
 npx route-bundle-size measure \
-  --app-dir <dir> \
   --out <file> \
+  [--app-dir <dir>] \
   [--stats <file>]
 ```
 
-- `--app-dir` (required): the app root. Chunk paths in the stats file resolve against it.
 - `--out` (required): where to write the snapshot JSON.
+- `--app-dir`: the app root. Chunk paths in the stats file resolve against it. Default `.`.
 - `--stats`: path to the stats file. Default: `<app-dir>/.next/diagnostics/route-bundle-stats.json`.
 
 `measure` gzips each unique chunk once, then sums the chunks of each route. It writes a snapshot:
@@ -70,14 +216,14 @@ npx route-bundle-size diff \
 ```
 
 - `--current` (required): the snapshot to check.
-- `--baseline`: the snapshot to compare with. If it is omitted or the file does not exist, `diff` prints the current sizes and exits `0`. Use this to bootstrap.
+- `--baseline`: the snapshot to compare with. Without it, `diff` shows only the current sizes (see [Output](#output)). If the file does not exist, `diff` prints a warning and works as if no baseline was given.
 - `--format`: `terminal` (default) prints a table to stdout. `markdown` writes a GitHub-flavored table to the file in `$GITHUB_STEP_SUMMARY`, or to stdout when that variable is not set.
 - `--config`: path to the config file. Default: `route-bundle-size.config.json` in the current directory, if it exists.
 - `--no-exclude`: ignore the `exclude` patterns from the config.
 
-Both inputs can be a `measure` snapshot or a raw `route-bundle-stats.json`. The tool detects the shape. A raw stats file has no gzip sizes, so with `metric: "compressed"` it is an error. Use `measure` snapshots, or set `metric` to `"raw"`.
+Both inputs can be a `measure` snapshot or a raw `route-bundle-stats.json`. The tool detects the shape. A raw stats file has no gzip sizes, so with `metric: "compressed"` it is an error. Use `measure` snapshots, or set `metric` to `"raw"`. If an input has no routes left after `exclude`, `diff` prints a warning.
 
-`--no-exclude` helps when you look for shared-chunk growth. Pages that ship only shared chunks, such as `/_not-found`, all grow by the same amount when a shared chunk grows.
+`--no-exclude` helps when you look for shared-chunk growth. Pages-router `/api/*` entries carry only the `_app` chunks, so they all grow by the same amount when a shared chunk grows. This is also why the example config below excludes `/api/**`.
 
 ## Config
 
@@ -89,7 +235,12 @@ Both inputs can be a `measure` snapshot or a raw `route-bundle-stats.json`. The
   "budget": {
     "metric": "compressed",
     "maxIncrease": "30kb",
-    "maxIncreasePercent": 10
+    "maxIncreasePercent": 10,
+    "maxSize": "300kb",
+    "overrides": [
+      { "match": "/dashboard", "maxSize": "450kb" },
+      { "match": "/blog/**", "maxIncrease": "10kb", "maxIncreasePercent": 5 }
+    ]
   }
 }
 ```
@@ -98,189 +249,110 @@ Both inputs can be a `measure` snapshot or a raw `route-bundle-stats.json`. The
 - `budget.metric`: `"compressed"` (gzip, default) or `"raw"` (uncompressed bytes from the stats file).
 - `budget.maxIncrease`: a byte count, or a string such as `"30kb"`, `"1.5mb"`, `"512b"`. Default `"30kb"`.
 - `budget.maxIncreasePercent`: a non-negative number. Default `10`.
+- `budget.maxSize`: the largest size a route may have, in the same format as `maxIncrease`. Not set by default.
+- `budget.overrides`: limits for specific routes. Default `[]`.
+
+A route fails when its size grows by at least `maxIncrease` bytes or at least `maxIncreasePercent` percent, whichever comes first. `maxIncreasePercent: 0` means any growth fails. To rely on one threshold only, set the other one high.
+
+With `maxSize` set, a route also fails when its size is above `maxSize`. This check needs no baseline, so it also applies to new routes and to a run without `--baseline`.
+
+Each entry in `overrides` has a `match` glob and any of `maxIncrease`, `maxIncreasePercent` and `maxSize`; keys that the entry leaves out keep the value from `budget`. A route uses the first entry whose `match` fits it, so put specific routes such as `/blog/[slug]` above broad globs such as `/blog/**`. `metric` is the same for all routes. `diff` prints a warning for an entry that matches no route.
 
-A route fails when its size grows by at least `maxIncrease` bytes or at least `maxIncreasePercent` percent, whichever comes first.
+Square brackets are literal, so `/blog/[slug]` matches only the dynamic route `/blog/[slug]`.
 
-Units in the config use 1024: `"30kb"` is 30,720 bytes. Output uses 1000-byte kB, so `"30kb"` prints as `30.7 kB`.
+Sizes use 1024-byte units: `"30kb"` is 30,720 bytes and the report prints it as `30 KiB`. `kib` and `mib` are accepted as the same units.
 
 Unknown keys are an error, so a typo such as `"excludes"` does not silently turn off filtering. A missing default config file means defaults are used. A missing file passed with `--config` is an error.
 
 ## Output
 
+The samples below use the example config above.
+
 Terminal (`--format terminal`, the default):
 
 ```text
-┌───────────────┬──────────┬───────────┬──────────────────────┬──────────┐
-│ Route         │ Baseline │   Current │              Δ bytes │ Δ chunks │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ /settings     │   185 kB │ (removed) │           -185 kB 🟢 │       -6 │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ /onboarding   │    (new) │    173 kB │        +173 kB (new) │       +5 │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ /dashboard    │   255 kB │    292 kB │ +37.1 kB (+14.5%) 🔴 │       +1 │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ /pricing      │   166 kB │    148 kB │ -17.9 kB (-10.8%) 🟢 │       -1 │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ /             │   161 kB │    162 kB │       +470 B (+0.3%) │        — │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ /blog/[slug]  │   157 kB │    157 kB │                    — │        — │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ /_not-found   │   138 kB │    138 kB │                    — │        — │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ TOTAL         │  1.06 MB │   1.07 MB │     +7.17 kB (+0.7%) │       -1 │
-├───────────────┼──────────┼───────────┼──────────────────────┼──────────┤
-│ avg per route │   177 kB │    178 kB │                      │          │
-└───────────────┴──────────┴───────────┴──────────────────────┴──────────┘
-🔴 exceeds +30.7 kB OR +10% compressed   🟢 notable improvement   7 route(s)
-::error::Bundle size regression — see step summary
+┌──────────────┬──────────┬────────────┬───────────────────────┬──────────┐
+│ Route        │ Baseline │    Current │               Δ bytes │ Δ chunks │
+├──────────────┼──────────┼────────────┼───────────────────────┼──────────┤
+│ /onboarding  │    (new) │ 318 KiB 🔴 │        +318 KiB (new) │       +5 │
+│ /dashboard   │  255 KiB │    292 KiB │ +37.1 KiB (+14.5%) 🔴 │       +1 │
+│ /settings    │  185 KiB │  (removed) │              -185 KiB │       -6 │
+│ /pricing     │  166 KiB │    148 KiB │ -17.9 KiB (-10.8%) 🟢 │       -1 │
+│ /            │  161 KiB │    162 KiB │        +470 B (+0.3%) │        — │
+│ /blog/[slug] │  157 KiB │    157 KiB │                     — │        — │
+│ /_not-found  │  138 KiB │    138 KiB │                     — │        — │
+└──────────────┴──────────┴────────────┴───────────────────────┴──────────┘
+Avg per route: 177 KiB → 203 KiB
+🔴 grew by at least 30 KiB or 10%, or is larger than 300 KiB (compressed; some routes have their own limits)   🟢 notable improvement   7 route(s)
+Bundle size budget exceeded for 2 route(s): /onboarding (max size 300 KiB), /dashboard (limit +30 KiB or +10%)
 ```
 
+The last line goes to stderr. Under GitHub Actions it starts with `::error::`, and GitHub shows it as an annotation.
+
 Markdown (`--format markdown`):
 
 ```markdown
-## 📦 Bundle size
-
-| Route          | First Load JS | Δ                    |
-| -------------- | ------------- | -------------------- |
-| `/settings`    | — (removed)   | -185 kB 🟢           |
-| `/onboarding`  | 173 kB        | +173 kB (new)        |
-| `/dashboard`   | 292 kB        | +37.1 kB (+14.5%) 🔴 |
-| `/pricing`     | 148 kB        | -17.9 kB (-10.8%) 🟢 |
-| `/`            | 162 kB        | +470 B (+0.3%)       |
-| `/blog/[slug]` | 157 kB        | —                    |
-| `/_not-found`  | 138 kB        | —                    |
+## Bundle size
+
+| Route          | First Load JS | Δ                     |
+| -------------- | ------------- | --------------------- |
+| `/onboarding`  | 318 KiB 🔴    | +318 KiB (new)        |
+| `/dashboard`   | 292 KiB       | +37.1 KiB (+14.5%) 🔴 |
+| `/settings`    | — (removed)   | -185 KiB              |
+| `/pricing`     | 148 KiB       | -17.9 KiB (-10.8%) 🟢 |
+| `/`            | 162 KiB       | +470 B (+0.3%)        |
+| `/blog/[slug]` | 157 KiB       | —                     |
+| `/_not-found`  | 138 KiB       | —                     |
 
 ### Summary
 
 - **Routes:** 7
-- **Total:** 1.06 MB → 1.07 MB (+7.17 kB, +0.7%)
-- **Avg per route:** 177 kB → 178 kB
-- **Chunks:** 30 → 29 (-1)
+- **Avg per route:** 177 KiB → 203 KiB
 
-🔴 exceeds `+30.7 kB` OR `+10%` compressed · 🟢 notable improvement (≥30.7 kB OR ≥10% smaller)
+🔴 grew by at least 30 KiB or 10%, or is larger than 300 KiB (compressed; some routes have their own limits) · 🟢 notable improvement
 ```
 
 How to read it:
 
-- Sizes and deltas use the budget metric. Rows are sorted by the size of the change.
-- 🔴 marks a route over budget. 🟢 marks a route that shrank by at least the budget.
-- A change under 250 bytes shows as `—`.
-- New routes are marked `(new)` and never fail the budget. Removed routes never fail either.
-- The `::error::` line goes to stderr. GitHub Actions shows it as an annotation.
+- Sizes and deltas use the budget metric. Failing routes come first, then the rest by the size of the change.
+- 🔴 on the Δ cell means the route grew past `maxIncrease` or `maxIncreasePercent`. 🔴 on the size cell means the route is larger than its `maxSize`.
+- 🟢 marks a route that shrank by at least the budget.
+- A change under 250 B shows as `—`, unless the route failed the growth rule.
+- New routes are marked `(new)`. They never fail the growth rule, but they can fail `maxSize`, as `/onboarding` does here. Removed routes never fail.
 
-Without a baseline, `diff` prints the current routes only. This table always shows raw bytes, and it goes to the step summary or stdout for both formats:
+Without a baseline, `diff` prints the current routes only and checks only `maxSize`. Sizes use the budget metric, or raw bytes when the input is a raw stats file. This table goes to the step summary or stdout for both formats:
 
 ```markdown
-## 📦 Bundle size
+## Bundle size
 
-Baseline not yet established. 6 routes captured.
+Baseline not yet established. 6 route(s) captured. Sizes are compressed.
 
 | Route          | First Load JS |
 | -------------- | ------------- |
-| `/dashboard`   | 969 kB        |
-| `/onboarding`  | 557 kB        |
-| `/`            | 514 kB        |
-| `/blog/[slug]` | 499 kB        |
-| `/pricing`     | 472 kB        |
-| `/_not-found`  | 432 kB        |
+| `/onboarding`  | 318 KiB 🔴    |
+| `/dashboard`   | 292 KiB       |
+| `/`            | 162 KiB       |
+| `/blog/[slug]` | 157 KiB       |
+| `/pricing`     | 148 KiB       |
+| `/_not-found`  | 138 KiB       |
+
+🔴 larger than its max size
 ```
 
-## Exit codes
-
-- `0`: every route is within budget, or there is no baseline yet. A `--baseline` path that does not exist also exits `0`, so the first run passes.
-- `1`: at least one route is over budget, or any error: bad config, unreadable input, missing chunk files, or raw stats used with `metric: "compressed"`.
-
-## GitHub Actions
-
-This workflow builds the PR head and its merge base in one job, then compares them. It writes the result to the job summary. It posts no PR comment and needs only `contents: read`, so it works for PRs from forks.
-
-```yaml
-name: Bundle size
-
-on:
-  pull_request:
-
-permissions:
-  contents: read
-
-jobs:
-  bundle-size:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 22
-          cache: npm
-
-      # An empty sha would make "git checkout --detach" stay at HEAD,
-      # so both sides would measure the same build and always pass.
-      - name: Resolve merge base
-        id: merge_base
-        run: |
-          sha=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
-          if [ -z "$sha" ]; then
-            echo "::error::Could not resolve a merge base with origin/${{ github.base_ref }}."
-            exit 1
-          fi
-          echo "sha=$sha" >> "$GITHUB_OUTPUT"
-          echo "head=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build current
-        run: npx next build
-
-      - name: Measure current
-        run: npx --yes route-bundle-size@0.1.0 measure --app-dir . --out "$RUNNER_TEMP/current.json"
+Here `/onboarding` is above `maxSize`, so this run exits `1`.
 
-      - name: Check out merge base
-        run: git checkout --detach ${{ steps.merge_base.outputs.sha }}
-
-      - name: Install dependencies at merge base
-        run: npm ci
-
-      - name: Build baseline
-        run: npx next build
-
-      - name: Return to PR head
-        run: git checkout --detach ${{ steps.merge_base.outputs.head }}
-
-      # .next is gitignored, so the baseline build survives the checkout.
-      # Running diff at the PR head uses the PR's config file.
-      - name: Measure baseline
-        run: npx --yes route-bundle-size@0.1.0 measure --app-dir . --out "$RUNNER_TEMP/baseline.json"
-
-      - name: Compare
-        run: |
-          npx --yes route-bundle-size@0.1.0 diff \
-            --current "$RUNNER_TEMP/current.json" \
-            --baseline "$RUNNER_TEMP/baseline.json" \
-            --format markdown
-```
-
-Notes:
+## Exit codes
 
-- Pin the tool version. Both snapshots are then made by the same version.
-- The tool runs through `npx`, so it does not need the project's `node_modules`. No reinstall is needed after returning to the PR head.
-- If the merge-base build fails, the job fails. It does not pass quietly.
-- GitHub shows the job summary even when the step exits `1`.
-- The cost is a second build in each PR run.
-- If your repo tracks `next-env.d.ts`, `next build` rewrites it and the checkout fails. Run `git checkout HEAD -- next-env.d.ts` before each `git checkout --detach`. Projects made with `create-next-app` ignore this file.
+- `0`: no route failed. This includes a run without a baseline, or with a `--baseline` path that does not exist, unless a route is above `maxSize`.
+- `1`: at least one route failed, or any error: bad config, unreadable input, missing chunk files.
 
 ## Limitations
 
 - The stats file `route-bundle-stats.json` has no official docs and no stability promise. A Next.js release can change it, so this package stays on 0.x.
 - Turbopack only. `next build --webpack` writes no stats file.
-- The default `--stats` path assumes the default `distDir` (`.next`). With a custom `distDir`, pass `--stats <app-dir>/<distDir>/diagnostics/route-bundle-stats.json`.
+- The default `--stats` path assumes the default `distDir` (`.next`). With a custom `distDir`, pass `--stats <app-dir>/<distDir>/diagnostics/route-bundle-stats.json`. The GitHub Action assumes the default.
 - Only first-load JS is measured.
-- One budget applies to every route. There are no per-route budgets.
+- App-router route handlers (`route.ts`) and middleware/proxy are not in the stats file. Pages-router `/api/*` entries carry only the `_app` chunks.
 
 ## Development
 
@@ -289,7 +361,10 @@ npm test
 npm run types
 ```
 
-The fixture `fixtures/sample-build/diagnostics/route-bundle-stats.json` is the parser contract. If Next.js changes the stats format, update `parseRawStats` in `src/stats.ts` and the fixture together.
+- `fixtures/sample-build/` is a small synthetic stats file. The CLI tests and the CI smoke run use it.
+- `fixtures/next-app/` is a real Next.js app. `.github/workflows/action-test.yml` builds it to test the action: a run without changes must pass, and a run that adds a lodash import to the home page must fail.
+
+To release, create a GitHub release with the tag `v<version in package.json>`. `release.yml` then publishes to npm with trusted publishing and moves the major tag (`v0`).
 
 ## License
 

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import { Command, Option } from "commander";
 import { loadConfig } from "./config.js";
-import { assertComparable, buildRows, buildSummary, FORMATS, loadSizes, renderBootstrap, renderMarkdown, renderTerminal, } from "./lib.js";
+import { assertComparable, assertMaxSizeComparable, buildRows, buildSummary, findUnmatchedOverrides, FORMATS, formatFailure, loadSizes, renderBootstrap, renderMarkdown, renderTerminal, } from "./lib.js";
 import { defaultStatsFile, measure, writeSnapshot } from "./measure.js";
 const writeSummary = (markdown) => {
     const summaryPath = process.env.GITHUB_STEP_SUMMARY;
@@ -12,25 +13,59 @@ const writeSummary = (markdown) => {
     }
     console.log(markdown);
 };
+const formatMessage = (level, message) => {
+    if (process.env.GITHUB_ACTIONS === "true") {
+        return `::${level}::${message}`;
+    }
+    return level === "warning" ? `Warning: ${message}` : message;
+};
+const loadInput = (filePath, exclude) => {
+    const loaded = loadSizes(filePath, exclude);
+    if (loaded.sizes.size === 0) {
+        console.error(formatMessage("warning", `No routes to check in ${filePath}. The file lists no routes, or "exclude" removes all of them.`));
+    }
+    return loaded;
+};
+const reportVerdict = (rows, anyExceeded, budget) => {
+    for (const match of findUnmatchedOverrides(rows, budget.overrides)) {
+        console.error(formatMessage("warning", `Override "${match}" matches no route.`));
+    }
+    if (anyExceeded) {
+        console.error(formatMessage("error", formatFailure(rows)));
+        process.exitCode = 1;
+    }
+};
 const diffCommand = new Command("diff")
-    .description("Diff route bundle sizes against a baseline; render markdown or terminal table; exit 1 on exceeded.")
-    .requiredOption("--current <file>", "Path to the PR's snapshot or route-bundle-stats.json")
-    .option("--baseline <file>", "Path to main's snapshot or route-bundle-stats.json (bootstrap mode if absent)")
-    .addOption(new Option("--format <format>", "Output format. 'terminal' (default) renders an aligned cli-table3 view for local debugging; 'markdown' writes a GitHub-flavored table to $GITHUB_STEP_SUMMARY and is the CI-only mode.")
+    .description("Compare route bundle sizes with a baseline and report the routes that grew past the budget.")
+    .requiredOption("--current <file>", "Snapshot or route-bundle-stats.json of the build to check")
+    .option("--baseline <file>", "Snapshot or route-bundle-stats.json to compare with. Without it, only the current sizes are shown")
+    .addOption(new Option("--format <format>", "Output format. 'terminal' prints a table to stdout. 'markdown' writes a GitHub-flavored table to $GITHUB_STEP_SUMMARY when it is set, otherwise to stdout")
     .choices([...FORMATS])
     .default("terminal"))
-    .option("--config <file>", "Path to route-bundle-size.config.json (default: the one in the current directory, if any)")
-    .option("--no-exclude", "Ignore the configured exclude patterns. Useful in diagnostic mode — bare pages surface pure shared-chunk drift.")
+    .option("--config <file>", "Path to the config file. Without it, route-bundle-size.config.json in the current directory is used if it exists")
+    .option("--no-exclude", 'Check every route and ignore the "exclude" patterns from the config')
     .action((options) => {
     const config = loadConfig({ configPath: options.config });
     const exclude = options.exclude ? config.exclude : [];
     const budget = config.budget;
-    const current = loadSizes(options.current, exclude);
+    const current = loadInput(options.current, exclude);
     if (options.baseline === undefined || !fs.existsSync(options.baseline)) {
-        writeSummary(renderBootstrap(current.sizes));
+        if (options.baseline !== undefined) {
+            console.error(formatMessage("warning", `Baseline file not found: ${options.baseline}. Nothing was compared, showing current sizes only.`));
+        }
+        assertMaxSizeComparable(current, budget);
+        const metric = budget.metric === "compressed" && !current.compressed
+            ? "raw"
+            : budget.metric;
+        const { rows, anyExceeded } = buildRows(current.sizes, new Map(), {
+            ...budget,
+            metric,
+        });
+        writeSummary(renderBootstrap(rows, metric));
+        reportVerdict(rows, anyExceeded, budget);
         return;
     }
-    const baseline = loadSizes(options.baseline, exclude);
+    const baseline = loadInput(options.baseline, exclude);
     assertComparable(current, baseline, budget.metric);
     const { rows, anyExceeded } = buildRows(current.sizes, baseline.sizes, budget);
     const summary = buildSummary(rows, budget.metric);
@@ -43,36 +78,48 @@ const diffCommand = new Command("diff")
     else {
         writeSummary(output);
     }
-    if (anyExceeded) {
-        console.error("::error::Bundle size regression — see step summary");
-        process.exit(1);
-    }
+    reportVerdict(rows, anyExceeded, budget);
 });
 const measureCommand = new Command("measure")
     .description("Gzip every unique first-load chunk once and write a snapshot with raw + compressed bytes per route.")
-    .requiredOption("--app-dir <dir>", "App root that the chunk paths in the stats file resolve against (the directory that contains .next)")
+    .option("--app-dir <dir>", "App root that the chunk paths in the stats file resolve against (the directory that contains .next)", ".")
     .option("--stats <file>", "Path to route-bundle-stats.json (default: <app-dir>/.next/diagnostics/route-bundle-stats.json)")
     .requiredOption("--out <file>", "Path to write the snapshot JSON to")
     .action((options) => {
-    var _a;
-    const statsFile = (_a = options.stats) !== null && _a !== void 0 ? _a : defaultStatsFile(options.appDir);
+    const statsFile = options.stats ?? defaultStatsFile(options.appDir);
     const { snapshot, uniqueChunkCount } = measure({
         appDir: options.appDir,
         statsFile,
     });
+    if (snapshot.routes.length === 0) {
+        console.error(formatMessage("warning", `${statsFile} lists no routes, so the snapshot is empty.`));
+    }
     writeSnapshot(options.out, snapshot);
     console.log(`Wrote ${options.out}: ${snapshot.routes.length} route(s), ${uniqueChunkCount} unique chunk(s)`);
 });
+const { version } = createRequire(import.meta.url)("../package.json");
 const program = new Command();
 program
     .name("route-bundle-size")
-    .description("Per-route bundle size budget for Next.js builds: measure compressed sizes, diff against a baseline, exit 1 on regression.");
+    .description("Per-route bundle size budget for Next.js Turbopack builds: measure compressed sizes, diff against a baseline, exit 1 on regression.")
+    .version(version);
 program.addCommand(diffCommand, { isDefault: true });
 program.addCommand(measureCommand);
-try {
-    program.parse();
+const commandNames = program.commands.map((command) => command.name());
+const firstArg = process.argv[2];
+if (firstArg !== undefined &&
+    !firstArg.startsWith("-") &&
+    !commandNames.includes(firstArg) &&
+    firstArg !== "help") {
+    console.error(`error: unknown command '${firstArg}'. Commands: ${commandNames.join(", ")}.`);
+    process.exitCode = 1;
 }
-catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
+else {
+    try {
+        program.parse();
+    }
+    catch (error) {
+        console.error(formatMessage("error", error instanceof Error ? error.message : String(error)));
+        process.exitCode = 1;
+    }
 }

package/dist/config.js

@@ -8,17 +8,24 @@ export const DEFAULT_CONFIG = {
         metric: "compressed",
         maxIncrease: 30 * 1024,
         maxIncreasePercent: 10,
+        maxSize: null,
+        overrides: [],
     },
 };
-const BYTE_UNITS = { b: 1, kb: 1024, mb: 1024 * 1024 };
-const BYTE_SIZE_PATTERN = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|mb)?\s*$/i;
+const BYTE_UNITS = {
+    b: 1,
+    kb: 1024,
+    kib: 1024,
+    mb: 1024 * 1024,
+    mib: 1024 * 1024,
+};
+const BYTE_SIZE_PATTERN = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|kib|mb|mib)?\s*$/i;
 export const parseByteSize = (value, field) => {
-    var _a;
     const numeric = typeof value === "number" ? value : Number.NaN;
     const match = typeof value === "string" ? BYTE_SIZE_PATTERN.exec(value) : null;
     const rounded = Math.round(match === null
         ? numeric
-        : Number(match[1]) * BYTE_UNITS[((_a = match[2]) !== null && _a !== void 0 ? _a : "b").toLowerCase()]);
+        : Number(match[1]) * BYTE_UNITS[(match[2] ?? "b").toLowerCase()]);
     if (!Number.isSafeInteger(rounded) || rounded < 0) {
         throw new Error(`Invalid ${field}: ${JSON.stringify(value)}. Expected a byte count or a size string like "30kb", "1.5mb", "512b".`);
     }
@@ -28,7 +35,7 @@ const asObject = (value, label) => {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new Error(`Invalid ${label}: expected a JSON object.`);
     }
-    return Object.assign({}, value);
+    return { ...value };
 };
 const assertKnownKeys = (value, validKeys, where) => {
     for (const key of Object.keys(value)) {
@@ -37,10 +44,40 @@ const assertKnownKeys = (value, validKeys, where) => {
         }
     }
 };
+const parsePercent = (value, field) => {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new Error(`Invalid ${field}: ${JSON.stringify(value)}. Expected a non-negative number.`);
+    }
+    return value;
+};
+const OVERRIDE_KEYS = ["match", "maxIncrease", "maxIncreasePercent", "maxSize"];
+const parseOverride = (value, index, source) => {
+    const label = (key) => `"budget.overrides[${index}]${key}" in ${source}`;
+    const raw = asObject(value, label(""));
+    assertKnownKeys(raw, OVERRIDE_KEYS, label(""));
+    if (typeof raw.match !== "string" || raw.match === "") {
+        throw new Error(`Invalid ${label(".match")}: ${JSON.stringify(raw.match)}. Expected a glob pattern.`);
+    }
+    const override = { match: raw.match };
+    if (raw.maxIncrease !== undefined) {
+        override.maxIncrease = parseByteSize(raw.maxIncrease, label(".maxIncrease"));
+    }
+    if (raw.maxIncreasePercent !== undefined) {
+        override.maxIncreasePercent = parsePercent(raw.maxIncreasePercent, label(".maxIncreasePercent"));
+    }
+    if (raw.maxSize !== undefined) {
+        override.maxSize = parseByteSize(raw.maxSize, label(".maxSize"));
+    }
+    return override;
+};
 export const parseConfig = (value, source) => {
     const raw = asObject(value, `config in ${source}`);
     assertKnownKeys(raw, Object.keys(DEFAULT_CONFIG), source);
-    const { exclude, budget: budgetValue } = Object.assign(Object.assign({}, DEFAULT_CONFIG), raw);
+    const { exclude, budget: budgetValue } = {
+        ...DEFAULT_CONFIG,
+        budget: {},
+        ...raw,
+    };
     if (!Array.isArray(exclude) ||
         !exclude.every((item) => typeof item === "string")) {
         throw new Error(`Invalid "exclude" in ${source}: expected an array of glob patterns.`);
@@ -48,23 +85,28 @@ export const parseConfig = (value, source) => {
     const budgetSource = `"budget" in ${source}`;
     const budgetRaw = asObject(budgetValue, budgetSource);
     assertKnownKeys(budgetRaw, Object.keys(DEFAULT_CONFIG.budget), budgetSource);
-    const { metric: metricValue, maxIncrease: maxIncreaseValue, maxIncreasePercent, } = Object.assign(Object.assign({}, DEFAULT_CONFIG.budget), budgetRaw);
+    const { metric: metricValue, maxIncrease: maxIncreaseValue, maxIncreasePercent: maxIncreasePercentValue, overrides: overridesValue, } = { ...DEFAULT_CONFIG.budget, ...budgetRaw };
     const metric = METRICS.find((known) => known === metricValue);
     if (metric === undefined) {
         throw new Error(`Invalid "budget.metric" in ${source}: ${JSON.stringify(metricValue)}. Valid values: ${METRICS.join(", ")}.`);
     }
-    if (typeof maxIncreasePercent !== "number" ||
-        !Number.isFinite(maxIncreasePercent) ||
-        maxIncreasePercent < 0) {
-        throw new Error(`Invalid "budget.maxIncreasePercent" in ${source}: ${JSON.stringify(maxIncreasePercent)}. Expected a non-negative number.`);
-    }
+    const maxIncreasePercent = parsePercent(maxIncreasePercentValue, `"budget.maxIncreasePercent" in ${source}`);
     const maxIncrease = parseByteSize(maxIncreaseValue, `"budget.maxIncrease" in ${source}`);
-    return { exclude, budget: { metric, maxIncrease, maxIncreasePercent } };
+    const maxSize = budgetRaw.maxSize === undefined
+        ? null
+        : parseByteSize(budgetRaw.maxSize, `"budget.maxSize" in ${source}`);
+    if (!Array.isArray(overridesValue)) {
+        throw new Error(`Invalid "budget.overrides" in ${source}: expected an array of objects.`);
+    }
+    const overrides = overridesValue.map((override, index) => parseOverride(override, index, source));
+    return {
+        exclude,
+        budget: { metric, maxIncrease, maxIncreasePercent, maxSize, overrides },
+    };
 };
 export const loadConfig = (options) => {
-    var _a, _b;
-    const cwd = (_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd();
-    const filePath = path.resolve(cwd, (_b = options.configPath) !== null && _b !== void 0 ? _b : CONFIG_FILE_NAME);
+    const cwd = options.cwd ?? process.cwd();
+    const filePath = path.resolve(cwd, options.configPath ?? CONFIG_FILE_NAME);
     if (!fs.existsSync(filePath)) {
         if (options.configPath === undefined) {
             return DEFAULT_CONFIG;

package/dist/lib.js

@@ -5,11 +5,13 @@ import picomatch from "picomatch";
 import prettyBytes from "pretty-bytes";
 import { parseRawStats, parseSnapshot, readJsonFile } from "./stats.js";
 export const FORMATS = ["markdown", "terminal"];
-export const MIN_DISPLAY = 250;
-const routeMatcher = (exclude) => picomatch(exclude, { dot: true });
+const MIN_DISPLAY = 250;
+const MAX_LISTED_ROUTES = 5;
+export const formatBytes = (bytes) => prettyBytes(bytes, { binary: true });
+const escapeBrackets = (pattern) => pattern.replace(/[[\]]/g, "\\$&");
+const routeMatcher = (exclude) => picomatch(exclude.map(escapeBrackets), { dot: true });
 export const isExcluded = (route, exclude) => routeMatcher(exclude)(route);
 export const loadSizes = (filePath, exclude) => {
-    var _a, _b;
     if (!fs.existsSync(filePath)) {
         throw new Error(`Input file not found: ${filePath}. Expected a "measure" snapshot or a route-bundle-stats.json (a Turbopack production build on Next.js >= 16.2 writes one).`);
     }
@@ -23,7 +25,7 @@ export const loadSizes = (filePath, exclude) => {
             }
             sizes.set(entry.route, {
                 bytes: entry.firstLoadUncompressedJsBytes,
-                chunks: (_b = (_a = entry.firstLoadChunkPaths) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0,
+                chunks: entry.firstLoadChunkPaths?.length ?? 0,
                 compressedBytes: null,
             });
         }
@@ -44,40 +46,61 @@ export const loadSizes = (filePath, exclude) => {
     }
     return { compressed: true, sizes };
 };
-export const hasCompressedData = (loaded) => loaded.compressed;
+const noCompressedDataError = (sides) => new Error(`Budget metric is "compressed" but ${sides.join(" and ")} ${sides.length > 1 ? "have" : "has"} no compressed data. Produce snapshots with the "measure" command, or set "budget.metric" to "raw" in the config.`);
 export const assertComparable = (current, baseline, metric) => {
     if (metric !== "compressed") {
         return;
     }
     const uncompressed = [
-        hasCompressedData(current) ? null : "current",
-        hasCompressedData(baseline) ? null : "baseline",
+        current.compressed ? null : "current",
+        baseline.compressed ? null : "baseline",
     ].filter((side) => side !== null);
     if (uncompressed.length > 0) {
-        throw new Error(`Budget metric is "compressed" but ${uncompressed.join(" and ")} ${uncompressed.length > 1 ? "have" : "has"} no compressed data. Produce snapshots with the "measure" command, or set "budget.metric" to "raw" in the config.`);
+        throw noCompressedDataError(uncompressed);
     }
 };
-const metricBytes = (stats, metric) => { var _a; return metric === "compressed" ? ((_a = stats.compressedBytes) !== null && _a !== void 0 ? _a : 0) : stats.bytes; };
+export const assertMaxSizeComparable = (current, budget) => {
+    const hasMaxSize = budget.maxSize !== null ||
+        budget.overrides.some((override) => override.maxSize !== undefined);
+    if (hasMaxSize && budget.metric === "compressed" && !current.compressed) {
+        throw noCompressedDataError(["current"]);
+    }
+};
+const metricBytes = (stats, metric) => metric === "compressed" ? (stats.compressedBytes ?? 0) : stats.bytes;
+const isFailing = (row) => row.exceeded || row.overMaxSize;
 export const buildRows = (current, baseline, budget) => {
-    var _a, _b, _c, _d;
     const allRoutes = new Set([...current.keys(), ...baseline.keys()]);
     const rows = [];
+    const globalLimits = {
+        maxIncrease: budget.maxIncrease,
+        maxIncreasePercent: budget.maxIncreasePercent,
+        maxSize: budget.maxSize,
+    };
+    const overrides = budget.overrides.map(({ match, ...limits }) => ({
+        matches: routeMatcher([match]),
+        limits,
+    }));
     let anyExceeded = false;
     for (const route of allRoutes) {
-        const cur = (_a = current.get(route)) !== null && _a !== void 0 ? _a : null;
-        const base = (_b = baseline.get(route)) !== null && _b !== void 0 ? _b : null;
+        const cur = current.get(route) ?? null;
+        const base = baseline.get(route) ?? null;
         const currentBytes = cur === null ? 0 : metricBytes(cur, budget.metric);
         const baselineBytes = base === null ? 0 : metricBytes(base, budget.metric);
         const delta = currentBytes - baselineBytes;
         const deltaPercent = base !== null && baselineBytes > 0 ? (delta / baselineBytes) * 100 : null;
-        const chunkDelta = ((_c = cur === null || cur === void 0 ? void 0 : cur.chunks) !== null && _c !== void 0 ? _c : 0) - ((_d = base === null || base === void 0 ? void 0 : base.chunks) !== null && _d !== void 0 ? _d : 0);
+        const chunkDelta = (cur?.chunks ?? 0) - (base?.chunks ?? 0);
+        const limits = {
+            ...globalLimits,
+            ...overrides.find((override) => override.matches(route))?.limits,
+        };
         // New routes (no baseline) never exceeded — a fresh page legitimately ships
         // its full size as "delta", which would otherwise always trip the abs rule.
         const exceeded = base !== null &&
             delta > 0 &&
-            (delta >= budget.maxIncrease ||
-                (deltaPercent !== null && deltaPercent >= budget.maxIncreasePercent));
-        if (exceeded) {
+            (delta >= limits.maxIncrease ||
+                (deltaPercent !== null && deltaPercent >= limits.maxIncreasePercent));
+        const overMaxSize = cur !== null && limits.maxSize !== null && currentBytes > limits.maxSize;
+        if (exceeded || overMaxSize) {
             anyExceeded = true;
         }
         rows.push({
@@ -87,101 +110,119 @@ export const buildRows = (current, baseline, budget) => {
             delta,
             deltaPercent,
             chunkDelta,
+            limits,
             exceeded,
+            overMaxSize,
         });
     }
-    rows.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+    rows.sort((a, b) => Number(isFailing(b)) - Number(isFailing(a)) ||
+        Math.abs(b.delta) - Math.abs(a.delta));
     return { rows, anyExceeded };
 };
+export const findUnmatchedOverrides = (rows, overrides) => overrides
+    .map((override) => override.match)
+    .filter((match) => {
+    const matches = routeMatcher([match]);
+    return !rows.some((row) => matches(row.route));
+});
 export const buildSummary = (rows, metric) => {
     let totalCurrent = 0;
     let totalBaseline = 0;
-    let chunksCurrent = 0;
-    let chunksBaseline = 0;
     let routesCurrent = 0;
     let routesBaseline = 0;
     for (const row of rows) {
         if (row.current !== null) {
             totalCurrent += metricBytes(row.current, metric);
-            chunksCurrent += row.current.chunks;
             routesCurrent += 1;
         }
         if (row.baseline !== null) {
             totalBaseline += metricBytes(row.baseline, metric);
-            chunksBaseline += row.baseline.chunks;
             routesBaseline += 1;
         }
     }
-    const totalDelta = totalCurrent - totalBaseline;
-    const totalDeltaPercent = totalBaseline > 0 ? (totalDelta / totalBaseline) * 100 : null;
     return {
         totalRoutes: rows.length,
         routesCurrent,
         routesBaseline,
-        totalCurrent,
-        totalBaseline,
-        totalDelta,
-        totalDeltaPercent,
         avgCurrent: routesCurrent > 0 ? totalCurrent / routesCurrent : 0,
         avgBaseline: routesBaseline > 0 ? totalBaseline / routesBaseline : 0,
-        chunksCurrent,
-        chunksBaseline,
     };
 };
-export const isNotableShrink = (row, budget) => row.delta < 0 &&
-    (row.delta <= -budget.maxIncrease ||
+export const isNotableShrink = (row) => row.current !== null &&
+    row.delta < 0 &&
+    (row.delta <= -row.limits.maxIncrease ||
         (row.deltaPercent !== null &&
-            row.deltaPercent <= -budget.maxIncreasePercent));
-export const formatDelta = (row, budget) => {
+            row.deltaPercent <= -row.limits.maxIncreasePercent));
+export const formatDelta = (row) => {
     // Sub-threshold deltas (incl. zero) are visual noise — show as "no change".
-    if (Math.abs(row.delta) < MIN_DISPLAY) {
+    if (!row.exceeded && Math.abs(row.delta) < MIN_DISPLAY) {
         return "—";
     }
     const sign = row.delta > 0 ? "+" : "";
-    const marker = row.exceeded
-        ? " 🔴"
-        : isNotableShrink(row, budget)
-            ? " 🟢"
-            : "";
+    const marker = row.exceeded ? " 🔴" : isNotableShrink(row) ? " 🟢" : "";
     // Removed: the size column already says "(removed)"; -100% is noise.
     if (row.current === null) {
-        return `${sign}${prettyBytes(row.delta)}${marker}`;
+        return `${sign}${formatBytes(row.delta)}${marker}`;
     }
     const percentLabel = row.deltaPercent === null
         ? "new"
         : `${sign}${row.deltaPercent.toFixed(1)}%`;
-    return `${sign}${prettyBytes(row.delta)} (${percentLabel})${marker}`;
-};
-export const formatSignedBytes = (bytes) => {
-    if (bytes === 0)
-        return "—";
-    const sign = bytes > 0 ? "+" : "";
-    return `${sign}${prettyBytes(bytes)}`;
+    return `${sign}${formatBytes(row.delta)} (${percentLabel})${marker}`;
 };
-export const formatPercent = (pct) => {
-    if (pct === null)
-        return "—";
-    const sign = pct > 0 ? "+" : "";
-    return `${sign}${pct.toFixed(1)}%`;
-};
-export const formatSignedInt = (n) => {
+const formatSignedInt = (n) => {
     if (n === 0)
         return "—";
     return n > 0 ? `+${n}` : `${n}`;
 };
-const budgetLegendSuffix = (budget) => budget.metric === "compressed" ? " compressed" : "";
+const formatCurrent = (row, metric, removedLabel) => {
+    if (row.current === null) {
+        return removedLabel;
+    }
+    const marker = row.overMaxSize ? " 🔴" : "";
+    return `${formatBytes(metricBytes(row.current, metric))}${marker}`;
+};
+const budgetLegend = (budget) => {
+    const maxSize = budget.maxSize === null
+        ? ""
+        : `, or is larger than ${formatBytes(budget.maxSize)}`;
+    const notes = [
+        budget.metric === "compressed" ? "compressed" : null,
+        budget.overrides.length > 0 ? "some routes have their own limits" : null,
+    ].filter((note) => note !== null);
+    const suffix = notes.length > 0 ? ` (${notes.join("; ")})` : "";
+    return `🔴 grew by at least ${formatBytes(budget.maxIncrease)} or ${budget.maxIncreasePercent}%${maxSize}${suffix}`;
+};
+const brokenLimits = ({ exceeded, overMaxSize, limits }) => {
+    const broken = [];
+    if (exceeded) {
+        broken.push(`limit +${formatBytes(limits.maxIncrease)} or +${limits.maxIncreasePercent}%`);
+    }
+    if (overMaxSize && limits.maxSize !== null) {
+        broken.push(`max size ${formatBytes(limits.maxSize)}`);
+    }
+    return broken.join(", ");
+};
+export const formatFailure = (rows) => {
+    const failing = rows.filter(isFailing);
+    const listed = failing
+        .slice(0, MAX_LISTED_ROUTES)
+        .map((row) => `${row.route} (${brokenLimits(row)})`)
+        .join(", ");
+    const more = failing.length > MAX_LISTED_ROUTES
+        ? ` (and ${failing.length - MAX_LISTED_ROUTES} more)`
+        : "";
+    return `Bundle size budget exceeded for ${failing.length} route(s): ${listed}${more}`;
+};
 export const renderMarkdown = (rows, summary, budget) => {
     if (rows.length === 0) {
-        return "## 📦 Bundle size\n\nNo client routes detected.";
+        return "## Bundle size\n\nNo client routes detected.";
     }
     const table = markdownTable([
         ["Route", "First Load JS", "Δ"],
         ...rows.map((r) => [
             `\`${r.route}\``,
-            r.current === null
-                ? "— (removed)"
-                : prettyBytes(metricBytes(r.current, budget.metric)),
-            formatDelta(r, budget),
+            formatCurrent(r, budget.metric, "— (removed)"),
+            formatDelta(r),
         ]),
     ]);
     const summaryLines = [
@@ -189,76 +230,60 @@ export const renderMarkdown = (rows, summary, budget) => {
         "### Summary",
         "",
         `- **Routes:** ${summary.totalRoutes}`,
-        `- **Total:** ${prettyBytes(summary.totalBaseline)} → ${prettyBytes(summary.totalCurrent)} (${formatSignedBytes(summary.totalDelta)}, ${formatPercent(summary.totalDeltaPercent)})`,
-        `- **Avg per route:** ${prettyBytes(summary.avgBaseline)} → ${prettyBytes(summary.avgCurrent)}`,
-        `- **Chunks:** ${summary.chunksBaseline} → ${summary.chunksCurrent} (${formatSignedInt(summary.chunksCurrent - summary.chunksBaseline)})`,
+        `- **Avg per route:** ${formatBytes(summary.avgBaseline)} → ${formatBytes(summary.avgCurrent)}`,
     ];
     return [
-        "## 📦 Bundle size",
+        "## Bundle size",
         "",
         table,
         ...summaryLines,
         "",
-        `🔴 exceeds \`+${prettyBytes(budget.maxIncrease)}\` OR \`+${budget.maxIncreasePercent}%\`${budgetLegendSuffix(budget)} · 🟢 notable improvement (≥${prettyBytes(budget.maxIncrease)} OR ≥${budget.maxIncreasePercent}% smaller)`,
+        `${budgetLegend(budget)} · 🟢 notable improvement`,
     ].join("\n");
 };
 export const renderTerminal = (rows, summary, budget) => {
     if (rows.length === 0) {
-        return "📦 Bundle size: no client routes detected.";
+        return "Bundle size: no client routes detected.";
     }
     const table = new Table({
         head: ["Route", "Baseline", "Current", "Δ bytes", "Δ chunks"],
         colAligns: ["left", "right", "right", "right", "right"],
-        style: { head: [], border: [] },
+        style: { head: [], border: [], compact: true },
     });
     for (const row of rows) {
         table.push([
             row.route,
             row.baseline === null
                 ? "(new)"
-                : prettyBytes(metricBytes(row.baseline, budget.metric)),
-            row.current === null
-                ? "(removed)"
-                : prettyBytes(metricBytes(row.current, budget.metric)),
-            formatDelta(row, budget),
-            row.chunkDelta === 0
-                ? "—"
-                : `${row.chunkDelta > 0 ? "+" : ""}${row.chunkDelta}`,
+                : formatBytes(metricBytes(row.baseline, budget.metric)),
+            formatCurrent(row, budget.metric, "(removed)"),
+            formatDelta(row),
+            formatSignedInt(row.chunkDelta),
         ]);
     }
-    table.push([
-        { content: "TOTAL", hAlign: "left" },
-        prettyBytes(summary.totalBaseline),
-        prettyBytes(summary.totalCurrent),
-        `${formatSignedBytes(summary.totalDelta)} (${formatPercent(summary.totalDeltaPercent)})`,
-        formatSignedInt(summary.chunksCurrent - summary.chunksBaseline),
-    ]);
-    table.push([
-        { content: "avg per route", hAlign: "left" },
-        prettyBytes(summary.avgBaseline),
-        prettyBytes(summary.avgCurrent),
-        "",
-        "",
-    ]);
     return [
         table.toString(),
-        `🔴 exceeds +${prettyBytes(budget.maxIncrease)} OR +${budget.maxIncreasePercent}%${budgetLegendSuffix(budget)}   🟢 notable improvement   ${summary.totalRoutes} route(s)`,
+        `Avg per route: ${formatBytes(summary.avgBaseline)} → ${formatBytes(summary.avgCurrent)}`,
+        `${budgetLegend(budget)}   🟢 notable improvement   ${summary.totalRoutes} route(s)`,
     ].join("\n");
 };
-export const renderBootstrap = (sizes) => {
-    const sorted = [...sizes.entries()].sort((a, b) => b[1].bytes - a[1].bytes);
+export const renderBootstrap = (rows, metric) => {
     const table = markdownTable([
         ["Route", "First Load JS"],
-        ...sorted.map(([route, stats]) => [
-            `\`${route}\``,
-            prettyBytes(stats.bytes),
+        ...rows.map((row) => [
+            `\`${row.route}\``,
+            formatCurrent(row, metric, "(removed)"),
         ]),
     ]);
+    const legend = rows.some((row) => row.overMaxSize)
+        ? ["", "🔴 larger than its max size"]
+        : [];
     return [
-        "## 📦 Bundle size",
+        "## Bundle size",
         "",
-        `Baseline not yet established. ${sizes.size} routes captured.`,
+        `Baseline not yet established. ${rows.length} route(s) captured. Sizes are ${metric}.`,
         "",
         table,
+        ...legend,
     ].join("\n");
 };

package/dist/measure.js

@@ -1,21 +1,22 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as zlib from "node:zlib";
-import { readRawStats, SNAPSHOT_SCHEMA_VERSION } from "./stats.js";
+import { isStringArray, readRawStats, SNAPSHOT_SCHEMA_VERSION, } from "./stats.js";
 export const defaultStatsFile = (appDir) => path.join(appDir, ".next", "diagnostics", "route-bundle-stats.json");
 const MISSING_CHUNKS_SHOWN = 5;
 export const measure = (options) => {
     const entries = readRawStats(options.statsFile);
-    const sizedWithoutChunks = entries.filter((entry) => {
-        var _a;
-        return entry.firstLoadUncompressedJsBytes > 0 &&
-            ((_a = entry.firstLoadChunkPaths) !== null && _a !== void 0 ? _a : []).length === 0;
-    });
+    const invalidChunkPathsIndex = entries.findIndex((entry) => !isStringArray(entry.firstLoadChunkPaths ?? []));
+    if (invalidChunkPathsIndex !== -1) {
+        throw new Error(`Invalid stats file ${options.statsFile}: entry ${invalidChunkPathsIndex} must have "firstLoadChunkPaths" as an array of strings.`);
+    }
+    const sizedWithoutChunks = entries.filter((entry) => entry.firstLoadUncompressedJsBytes > 0 &&
+        (entry.firstLoadChunkPaths ?? []).length === 0);
     if (sizedWithoutChunks.length > 0) {
         throw new Error(`${sizedWithoutChunks.length} route(s) in ${options.statsFile} report first-load JS but list no "firstLoadChunkPaths": ${sizedWithoutChunks.map((entry) => entry.route).join(", ")}. Their compressed size would be recorded as 0 and the snapshot would understate their size, so the budget could not see them grow.`);
     }
     const uniqueChunks = [
-        ...new Set(entries.flatMap((entry) => { var _a; return (_a = entry.firstLoadChunkPaths) !== null && _a !== void 0 ? _a : []; })),
+        ...new Set(entries.flatMap((entry) => entry.firstLoadChunkPaths ?? [])),
     ];
     const missing = uniqueChunks.filter((chunk) => !fs.existsSync(path.resolve(options.appDir, chunk)));
     if (missing.length > 0) {
@@ -33,12 +34,11 @@ export const measure = (options) => {
     const snapshot = {
         schemaVersion: SNAPSHOT_SCHEMA_VERSION,
         routes: entries.map((entry) => {
-            var _a;
-            const chunks = (_a = entry.firstLoadChunkPaths) !== null && _a !== void 0 ? _a : [];
+            const chunks = entry.firstLoadChunkPaths ?? [];
             return {
                 route: entry.route,
                 rawBytes: entry.firstLoadUncompressedJsBytes,
-                compressedBytes: chunks.reduce((total, chunk) => { var _a; return total + ((_a = compressedByChunk.get(chunk)) !== null && _a !== void 0 ? _a : 0); }, 0),
+                compressedBytes: chunks.reduce((total, chunk) => total + (compressedByChunk.get(chunk) ?? 0), 0),
                 chunkPaths: chunks,
             };
         }),

package/dist/stats.js

@@ -2,13 +2,13 @@ import * as fs from "node:fs";
 export const SNAPSHOT_SCHEMA_VERSION = 1;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
-const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+export const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 export const parseRawStats = (value, source) => {
     if (!Array.isArray(value)) {
         throw new Error(`Invalid stats file ${source}: expected a top-level array of route entries.`);
     }
     return value.map((entry, index) => {
-        const { route, firstLoadUncompressedJsBytes, firstLoadChunkPaths } = (entry !== null && entry !== void 0 ? entry : {});
+        const { route, firstLoadUncompressedJsBytes, firstLoadChunkPaths } = (entry ?? {});
         if (typeof route !== "string" ||
             !isFiniteNumber(firstLoadUncompressedJsBytes)) {
             throw new Error(`Invalid stats file ${source}: entry ${index} must have a string "route" and a finite "firstLoadUncompressedJsBytes".`);
@@ -27,7 +27,7 @@ export const readJsonFile = (filePath) => {
 };
 export const readRawStats = (filePath) => {
     if (!fs.existsSync(filePath)) {
-        throw new Error(`Stats file not found: ${filePath}. A Turbopack production build on Next.js >= 16.2 writes this file.`);
+        throw new Error(`Stats file not found: ${filePath}. Possible causes: --app-dir does not point to the app root; the app was built with webpack (next build --webpack) or with Next.js older than 16.2, which write no stats file; next.config sets a custom distDir, so pass --stats <app-dir>/<distDir>/diagnostics/route-bundle-stats.json.`);
     }
     return parseRawStats(readJsonFile(filePath), filePath);
 };
@@ -42,7 +42,8 @@ export const parseSnapshot = (value, source) => {
         throw new Error(`Invalid snapshot ${source}: "routes" must be an array.`);
     }
     const routes = value.routes.map((entry, index) => {
-        const { route, rawBytes, compressedBytes, chunkPaths } = (entry !== null && entry !== void 0 ? entry : {});
+        const { route, rawBytes, compressedBytes, chunkPaths } = (entry ??
+            {});
         if (typeof route !== "string" ||
             !isFiniteNumber(rawBytes) ||
             !isStringArray(chunkPaths) ||

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "route-bundle-size",
-  "version": "0.1.0",
-  "description": "Per-route bundle size budget for Next.js builds: measure compressed sizes, diff against a baseline, exit 1 on regression.",
+  "version": "0.2.0",
+  "description": "Per-route bundle size budget for Next.js Turbopack builds: measure compressed sizes, diff against a baseline, exit 1 on regression.",
   "keywords": [
     "nextjs",
     "turbopack",
@@ -33,7 +33,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepack": "npm run build",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test": "NODE_OPTIONS='--experimental-vm-modules --disable-warning=ExperimentalWarning' jest",
     "types": "tsc --noEmit"
   },
   "dependencies": {
@@ -45,10 +45,9 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
-    "@types/node": "^25.6.0",
+    "@types/node": "^22.12.0",
     "@types/picomatch": "^4.0.3",
     "jest": "^30.4.2",
-    "jest-environment-node": "^30.4.1",
     "ts-jest": "^29.4.6",
     "tsx": "^4.9.1",
     "typescript": "^6.0.3"