CI and pull requests

The PR comment is the point. Every comment is read by every reviewer, in context, at the moment it matters.

The action

.github/workflows/crust.yml

name: crust

on: pull_request

permissions:
  contents: write        # push snapshots to perf-history
  pull-requests: write   # post the comment

jobs:
  crust:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx next build
      - uses: moumensoliman/crust/action@main
        with:
          working-directory: .
          baseline: main

It fetches snapshot history, runs the check, posts or updates the comment, and publishes the new snapshot.

Budgets

Create .perf/budgets.json at the workspace root. Nothing is enforced until this file exists.

.perf/budgets.json

{
  "defaultFirstLoadBytes": 250000,
  "firstLoadBytes": {
    "/products/[slug]": 180000
  },
  "maxGrowth": 0.05,
  "defaultMinShellRatio": 0.6,
  "minShellRatio": {
    "/checkout": 0.8
  }
}

Both axes are covered on purpose. A check that only guards bytes will happily pass a PR that silently halved your static shell — which is the regression nothing else catches.

See the budgets reference for every field.

The comment

### crust: 2 budget breaches

**Budget breaches**

- `/dashboard` — static shell is 39% of the route, below the 60% floor
  - blame: `cookies() at app/dashboard/page.tsx:18`
- `/products/[slug]` — static shell is 45% of the route, below the 60% floor
  - blame: `uncached fetch at lib/http.ts:3`

| Route | First load | Δ | Shell | Δ |
|---|--:|--:|--:|--:|
| `/products/[slug]` | 543.2 kB | — | 45% | -55% |

**Fell out of the static shell**

- `/products/[slug]` — `<ProductGallery>` — uncached fetch at lib/http.ts:3

The comment carries a hidden  marker so the action updates the existing one instead of stacking a new comment on every push. crust ci exits non-zero on a breach.

Snapshot history

A fresh CI checkout has no .perf/ directory, so the baseline lives on an orphan branch:

npx crust history fetch   # pull snapshots into .perf/
npx crust history push    # publish this build's snapshot

An orphan branch shares no history with your code, so it can grow and be truncated freely without polluting git log or complicating rebases.

Fork pull requests get the comment but skip the push. A fork’s GITHUB_TOKEN is read-only on the base repository, so history push reports and exits cleanly rather than failing the check. Diffs still work from whatever snapshots the branch already holds.

Retention

npx crust prune

Full fidelity for the newest 50 builds, then one snapshot per commit, then module detail dropped after 90 days. Route totals and shell ratios are kept forever — they are tiny, and they are what anyone looks at a year later.

Getting started

Concepts

Guides

Reference

CI and pull requests

The action

Budgets

The comment

Snapshot history

Retention

​The action

​Budgets

​The comment

​Snapshot history

​Retention

The action

Budgets

The comment

Snapshot history

Retention