route-bundle-size 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Patrakeev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,296 @@
-# Temporary Holding Version
+# route-bundle-size
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+- 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.
+
+## 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.
+
+## Quick start
+
+```bash
+# At the baseline commit
+npx next build
+npx route-bundle-size measure --app-dir . --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 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`.
+
+## Commands
+
+### `measure`
+
+```bash
+npx route-bundle-size measure \
+  --app-dir <dir> \
+  --out <file> \
+  [--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.
+- `--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:
+
+```json
+{ "schemaVersion": 1, "routes": [{ "route": "/", "rawBytes": 65000, "compressedBytes": 49276, "chunkPaths": ["..."] }] }
+```
+
+It fails if a chunk file is missing under `--app-dir`. It also fails if a route reports first-load JS but lists no chunk paths. A missing chunk is never counted as zero.
+
+Run `measure` right after each build. The next build overwrites `.next`.
+
+### `diff`
+
+`diff` is the default command, so `npx route-bundle-size --current ...` works too.
+
+```bash
+npx route-bundle-size diff \
+  --current <file> \
+  [--baseline <file>] \
+  [--format terminal|markdown] \
+  [--config <file>] \
+  [--no-exclude]
+```
+
+- `--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.
+- `--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"`.
+
+`--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.
+
+## Config
+
+`route-bundle-size.config.json` in the current directory, or the file passed with `--config`. All keys are optional.
+
+```json
+{
+  "exclude": ["/api/**"],
+  "budget": {
+    "metric": "compressed",
+    "maxIncrease": "30kb",
+    "maxIncreasePercent": 10
+  }
+}
+```
+
+- `exclude`: glob patterns ([picomatch](https://github.com/micromatch/picomatch)) matched against the route. Default `[]`.
+- `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`.
+
+A route fails when its size grows by at least `maxIncrease` bytes or at least `maxIncreasePercent` percent, whichever comes first.
+
+Units in the config use 1024: `"30kb"` is 30,720 bytes. Output uses 1000-byte kB, so `"30kb"` prints as `30.7 kB`.
+
+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
+
+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
+```
+
+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        | —                    |
+
+### 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)
+
+🔴 exceeds `+30.7 kB` OR `+10%` compressed · 🟢 notable improvement (≥30.7 kB OR ≥10% smaller)
+```
+
+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.
+
+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:
+
+```markdown
+## 📦 Bundle size
+
+Baseline not yet established. 6 routes captured.
+
+| Route          | First Load JS |
+| -------------- | ------------- |
+| `/dashboard`   | 969 kB        |
+| `/onboarding`  | 557 kB        |
+| `/`            | 514 kB        |
+| `/blog/[slug]` | 499 kB        |
+| `/pricing`     | 472 kB        |
+| `/_not-found`  | 432 kB        |
+```
+
+## 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"
+
+      - 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:
+
+- 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.
+
+## 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`.
+- Only first-load JS is measured.
+- One budget applies to every route. There are no per-route budgets.
+
+## Development
+
+```bash
+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.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import { Command, Option } from "commander";
+import { loadConfig } from "./config.js";
+import { assertComparable, buildRows, buildSummary, FORMATS, loadSizes, renderBootstrap, renderMarkdown, renderTerminal, } from "./lib.js";
+import { defaultStatsFile, measure, writeSnapshot } from "./measure.js";
+const writeSummary = (markdown) => {
+    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryPath !== undefined) {
+        fs.appendFileSync(summaryPath, markdown + "\n");
+        return;
+    }
+    console.log(markdown);
+};
+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.")
+    .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.")
+    .action((options) => {
+    const config = loadConfig({ configPath: options.config });
+    const exclude = options.exclude ? config.exclude : [];
+    const budget = config.budget;
+    const current = loadSizes(options.current, exclude);
+    if (options.baseline === undefined || !fs.existsSync(options.baseline)) {
+        writeSummary(renderBootstrap(current.sizes));
+        return;
+    }
+    const baseline = loadSizes(options.baseline, exclude);
+    assertComparable(current, baseline, budget.metric);
+    const { rows, anyExceeded } = buildRows(current.sizes, baseline.sizes, budget);
+    const summary = buildSummary(rows, budget.metric);
+    const output = options.format === "terminal"
+        ? renderTerminal(rows, summary, budget)
+        : renderMarkdown(rows, summary, budget);
+    if (options.format === "terminal") {
+        console.log(output);
+    }
+    else {
+        writeSummary(output);
+    }
+    if (anyExceeded) {
+        console.error("::error::Bundle size regression — see step summary");
+        process.exit(1);
+    }
+});
+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("--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 { snapshot, uniqueChunkCount } = measure({
+        appDir: options.appDir,
+        statsFile,
+    });
+    writeSnapshot(options.out, snapshot);
+    console.log(`Wrote ${options.out}: ${snapshot.routes.length} route(s), ${uniqueChunkCount} unique chunk(s)`);
+});
+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.");
+program.addCommand(diffCommand, { isDefault: true });
+program.addCommand(measureCommand);
+try {
+    program.parse();
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+}

package/dist/config.js

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const CONFIG_FILE_NAME = "route-bundle-size.config.json";
+export const METRICS = ["raw", "compressed"];
+export const DEFAULT_CONFIG = {
+    exclude: [],
+    budget: {
+        metric: "compressed",
+        maxIncrease: 30 * 1024,
+        maxIncreasePercent: 10,
+    },
+};
+const BYTE_UNITS = { b: 1, kb: 1024, mb: 1024 * 1024 };
+const BYTE_SIZE_PATTERN = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|mb)?\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()]);
+    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".`);
+    }
+    return rounded;
+};
+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);
+};
+const assertKnownKeys = (value, validKeys, where) => {
+    for (const key of Object.keys(value)) {
+        if (!validKeys.includes(key)) {
+            throw new Error(`Unknown key "${key}" in ${where}. Valid keys: ${validKeys.join(", ")}.`);
+        }
+    }
+};
+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);
+    if (!Array.isArray(exclude) ||
+        !exclude.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid "exclude" in ${source}: expected an array of glob patterns.`);
+    }
+    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 = 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 maxIncrease = parseByteSize(maxIncreaseValue, `"budget.maxIncrease" in ${source}`);
+    return { exclude, budget: { metric, maxIncrease, maxIncreasePercent } };
+};
+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);
+    if (!fs.existsSync(filePath)) {
+        if (options.configPath === undefined) {
+            return DEFAULT_CONFIG;
+        }
+        throw new Error(`Config file not found: ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseConfig(parsed, filePath);
+};

package/dist/lib.js

@@ -0,0 +1,264 @@
+import * as fs from "node:fs";
+import Table from "cli-table3";
+import { markdownTable } from "markdown-table";
+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 });
+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).`);
+    }
+    const data = readJsonFile(filePath);
+    const excluded = routeMatcher(exclude);
+    const sizes = new Map();
+    if (Array.isArray(data)) {
+        for (const entry of parseRawStats(data, filePath)) {
+            if (excluded(entry.route)) {
+                continue;
+            }
+            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,
+                compressedBytes: null,
+            });
+        }
+        return { compressed: false, sizes };
+    }
+    if (typeof data !== "object" || data === null || !("schemaVersion" in data)) {
+        throw new Error(`Unrecognized input ${filePath}: expected a route-bundle-stats.json array or a route-bundle-size snapshot with "schemaVersion".`);
+    }
+    for (const entry of parseSnapshot(data, filePath).routes) {
+        if (excluded(entry.route)) {
+            continue;
+        }
+        sizes.set(entry.route, {
+            bytes: entry.rawBytes,
+            chunks: entry.chunkPaths.length,
+            compressedBytes: entry.compressedBytes,
+        });
+    }
+    return { compressed: true, sizes };
+};
+export const hasCompressedData = (loaded) => loaded.compressed;
+export const assertComparable = (current, baseline, metric) => {
+    if (metric !== "compressed") {
+        return;
+    }
+    const uncompressed = [
+        hasCompressedData(current) ? null : "current",
+        hasCompressedData(baseline) ? 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.`);
+    }
+};
+const metricBytes = (stats, metric) => { var _a; return metric === "compressed" ? ((_a = stats.compressedBytes) !== null && _a !== void 0 ? _a : 0) : stats.bytes; };
+export const buildRows = (current, baseline, budget) => {
+    var _a, _b, _c, _d;
+    const allRoutes = new Set([...current.keys(), ...baseline.keys()]);
+    const rows = [];
+    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 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);
+        // 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) {
+            anyExceeded = true;
+        }
+        rows.push({
+            route,
+            current: cur,
+            baseline: base,
+            delta,
+            deltaPercent,
+            chunkDelta,
+            exceeded,
+        });
+    }
+    rows.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+    return { rows, anyExceeded };
+};
+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 ||
+        (row.deltaPercent !== null &&
+            row.deltaPercent <= -budget.maxIncreasePercent));
+export const formatDelta = (row, budget) => {
+    // Sub-threshold deltas (incl. zero) are visual noise — show as "no change".
+    if (Math.abs(row.delta) < MIN_DISPLAY) {
+        return "—";
+    }
+    const sign = row.delta > 0 ? "+" : "";
+    const marker = row.exceeded
+        ? " 🔴"
+        : isNotableShrink(row, budget)
+            ? " 🟢"
+            : "";
+    // Removed: the size column already says "(removed)"; -100% is noise.
+    if (row.current === null) {
+        return `${sign}${prettyBytes(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)}`;
+};
+export const formatPercent = (pct) => {
+    if (pct === null)
+        return "—";
+    const sign = pct > 0 ? "+" : "";
+    return `${sign}${pct.toFixed(1)}%`;
+};
+export const formatSignedInt = (n) => {
+    if (n === 0)
+        return "—";
+    return n > 0 ? `+${n}` : `${n}`;
+};
+const budgetLegendSuffix = (budget) => budget.metric === "compressed" ? " compressed" : "";
+export const renderMarkdown = (rows, summary, budget) => {
+    if (rows.length === 0) {
+        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),
+        ]),
+    ]);
+    const summaryLines = [
+        "",
+        "### 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)})`,
+    ];
+    return [
+        "## 📦 Bundle size",
+        "",
+        table,
+        ...summaryLines,
+        "",
+        `🔴 exceeds \`+${prettyBytes(budget.maxIncrease)}\` OR \`+${budget.maxIncreasePercent}%\`${budgetLegendSuffix(budget)} · 🟢 notable improvement (≥${prettyBytes(budget.maxIncrease)} OR ≥${budget.maxIncreasePercent}% smaller)`,
+    ].join("\n");
+};
+export const renderTerminal = (rows, summary, budget) => {
+    if (rows.length === 0) {
+        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: [] },
+    });
+    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}`,
+        ]);
+    }
+    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)`,
+    ].join("\n");
+};
+export const renderBootstrap = (sizes) => {
+    const sorted = [...sizes.entries()].sort((a, b) => b[1].bytes - a[1].bytes);
+    const table = markdownTable([
+        ["Route", "First Load JS"],
+        ...sorted.map(([route, stats]) => [
+            `\`${route}\``,
+            prettyBytes(stats.bytes),
+        ]),
+    ]);
+    return [
+        "## 📦 Bundle size",
+        "",
+        `Baseline not yet established. ${sizes.size} routes captured.`,
+        "",
+        table,
+    ].join("\n");
+};

package/dist/measure.js

@@ -0,0 +1,51 @@
+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";
+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;
+    });
+    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 : []; })),
+    ];
+    const missing = uniqueChunks.filter((chunk) => !fs.existsSync(path.resolve(options.appDir, chunk)));
+    if (missing.length > 0) {
+        const shown = missing.slice(0, MISSING_CHUNKS_SHOWN).join(", ");
+        const rest = missing.length > MISSING_CHUNKS_SHOWN
+            ? ` (and ${missing.length - MISSING_CHUNKS_SHOWN} more)`
+            : "";
+        throw new Error(`${missing.length} chunk file(s) referenced by ${options.statsFile} are missing under --app-dir ${options.appDir}: ${shown}${rest}. Point --app-dir at the app root that the stats paths resolve against.`);
+    }
+    const compressedByChunk = new Map();
+    for (const chunk of uniqueChunks) {
+        compressedByChunk.set(chunk, zlib.gzipSync(fs.readFileSync(path.resolve(options.appDir, chunk)))
+            .byteLength);
+    }
+    const snapshot = {
+        schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+        routes: entries.map((entry) => {
+            var _a;
+            const chunks = (_a = entry.firstLoadChunkPaths) !== null && _a !== void 0 ? _a : [];
+            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),
+                chunkPaths: chunks,
+            };
+        }),
+    };
+    return { snapshot, uniqueChunkCount: uniqueChunks.length };
+};
+export const writeSnapshot = (filePath, snapshot) => {
+    fs.mkdirSync(path.dirname(path.resolve(filePath)), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(snapshot, null, 2)}\n`);
+};

package/dist/stats.js

@@ -0,0 +1,56 @@
+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 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 : {});
+        if (typeof route !== "string" ||
+            !isFiniteNumber(firstLoadUncompressedJsBytes)) {
+            throw new Error(`Invalid stats file ${source}: entry ${index} must have a string "route" and a finite "firstLoadUncompressedJsBytes".`);
+        }
+        return { route, firstLoadUncompressedJsBytes, firstLoadChunkPaths };
+    });
+};
+export const readJsonFile = (filePath) => {
+    const text = fs.readFileSync(filePath, "utf8");
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+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.`);
+    }
+    return parseRawStats(readJsonFile(filePath), filePath);
+};
+export const parseSnapshot = (value, source) => {
+    if (!isRecord(value)) {
+        throw new Error(`Invalid snapshot ${source}: expected a JSON object.`);
+    }
+    if (value.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+        throw new Error(`Unsupported snapshot schemaVersion in ${source}: ${JSON.stringify(value.schemaVersion)}. Expected ${SNAPSHOT_SCHEMA_VERSION}.`);
+    }
+    if (!Array.isArray(value.routes)) {
+        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 : {});
+        if (typeof route !== "string" ||
+            !isFiniteNumber(rawBytes) ||
+            !isStringArray(chunkPaths) ||
+            !isFiniteNumber(compressedBytes) ||
+            compressedBytes < 0) {
+            throw new Error(`Invalid snapshot ${source}: route ${index} must have a string "route", a finite "rawBytes", a "chunkPaths" array of strings, and a non-negative "compressedBytes".`);
+        }
+        return { route, rawBytes, compressedBytes, chunkPaths };
+    });
+    return { schemaVersion: SNAPSHOT_SCHEMA_VERSION, routes };
+};

package/package.json

@@ -1,6 +1,56 @@
 {
+  "$schema": "https://www.schemastore.org/package.json",
   "name": "route-bundle-size",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "keywords": [
+    "nextjs",
+    "turbopack",
+    "bundle-size",
+    "performance-budget",
+    "ci",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bra31k/route-bundle-size.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bra31k/route-bundle-size/issues"
+  },
+  "homepage": "https://github.com/bra31k/route-bundle-size#readme",
+  "type": "module",
+  "bin": {
+    "route-bundle-size": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "cli-table3": "^0.6.5",
+    "commander": "^15.0.0",
+    "markdown-table": "^3.0.4",
+    "picomatch": "^4.0.4",
+    "pretty-bytes": "^7.1.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.4.1",
+    "@types/node": "^25.6.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"
+  }
+}