Skip to main content
All commands accept --cwd <dir> (default: current directory) pointing at the Next.js app, and most accept --dist-dir <dir> (default: .next).

​
analyze

Analyse a production build and record a snapshot.

​
diff

Compare this build against a stored snapshot. Exits non-zero if no baseline is found.
ref accepts a build id, a git SHA, a branch name, or HEAD~3. Defaults to HEAD~1.

​
ci

Check budgets and print a PR comment. Exits non-zero on a breach.
Defaults to comparing against main. Without .perf/budgets.json nothing is enforced and nothing fails. See budgets.

​
report

Write a self-contained HTML report.
No external requests: styles, script and data are inlined.

​
manifest

Write the snapshot where the in-app widget can fetch it.
The manifest lists every route, source path and component name in your app. Generate it in analyze builds only.

​
history

Sync snapshots with the orphan perf-history branch.
push reports and exits cleanly when the remote rejects it — a fork PR’s token is read-only on the base repository, and that is not a failure worth breaking the check over.

​
prune

Apply the retention ladder.
Newest 50 builds at full fidelity → one per commit → module detail dropped after 90 days. Route totals and shell ratios are kept forever.

​
synthetic

Measure routes against a running deployment. Needs Playwright as an optional peer.

​
list

List stored snapshots, newest first.

​
Exit codes

Any unsupported project — Next outside 15–16, a dev-only build, a Pages Router app — throws with a message naming the reason rather than emitting numbers it cannot stand behind.