before-and-after
Capture before/after proof for a PR and put it in the PR body. Screenshots for anything with a visible surface, measured numbers for anything without. Use when opening a PR, when the user says "before
SKILL.mdskills/before-and-after/SKILL.md
GitHubBefore and after
Every PR carries proof. A reviewer should be able to tell the change works without reading the diff.
Package is
@vercel/before-and-after. Plainbefore-and-afteron npm is a different package, do not install it.
Adapted from vercel-labs/before-and-after, PolyForm Shield 1.0.0, license in this folder.
Data rule, read this first
There is no account and no database, so the only data on screen is whatever is typed into the editor. Billy keeps the draft in the browser's
localStorage(billy_invoice_data). Before capturing, load a made-up invoice with obviously fake names, addresses, GSTIN and bank details, or a profession preset. Never capture a draft that holds someone's real client or bank details. If the browser profile you drive has been used for real invoices, clearbilly_invoice_datafirst, or use a fresh profile. The dev server isbun run devon http://localhost:3000. Routes are/and/editor. For a WYSIWYG change, capture the exported PDF as well as the screen, since the PDF is the thing that has to match.Never upload to the default host. The upstream default adapter posts to
0x0.st, a public paste host with no auth and no delete. This kit defaults to the gist adapter instead, which creates a secret, unlisted gist. Secret is not access-controlled, anyone with the URL can read it, so it is a step up from a public paste host and not a substitute for keeping something private. Set it explicitly every time:IMAGE_ADAPTER=gist ./scripts/upload-and-copy.sh before.png after.png --markdownBetter still, drag the PNGs into the PR body on github.com, which stores them on GitHub behind the repo's own access control. Use that for anything you are unsure about.
Which kind of proof
| Change touches | Proof |
|---|---|
| Any page or component a user sees | Screenshot pair |
| A flow that only makes sense over time | Short screen recording, see evidence-driven-testing |
| Latency, token cost, query count, bundle size | Measured numbers, before and after, same conditions |
| A migration | Row counts and index list before and after |
| Backend logic with no surface | Test output, or a curl pair showing the old and new response |
A change with no visible surface still needs proof. Numbers count.
Capture
Do not switch branches, stash, or guess what "before" is. Current state is after. Ask for the before source when it is not obvious:
What should I use for the before state: the deployed app, a preview URL, or should I stash to the base commit and capture locally?
Record this project's local ports here. Confirm the port answers your dev server before trusting it, since ports are global and worktrees share them:
lsof -i :<port>
Then:
# Pre-flight
which before-and-after || npm install -g @vercel/before-and-after
# Two URLs
before-and-after "http://localhost:<port>/<route>" "http://localhost:<port>/<route>"
# One component, which is usually what you want, it keeps other firms' data out
before-and-after <url1> <url2> ".the-component"
# Two PNGs you already captured while developing
before-and-after before.png after.png --markdown
# Viewports
before-and-after <url1> <url2> --mobile # 375x812
before-and-after <url1> <url2> --tablet # 768x1024
| Flag | Meaning |
|---|---|
-m, --mobile |
375x812 |
-t, --tablet |
768x1024 |
--size <WxH> |
Custom viewport |
-f, --full |
Full scroll, only when asked |
-s, --selector |
CSS selector |
-o, --output |
Output dir, default ~/Downloads |
--markdown |
Upload and print the table |
--upload-url |
Custom endpoint |
Do not pass --full unless the user asks for a full-page capture. A full page
pulls in the sidebar and any surrounding chrome, which is how real data leaks
into a screenshot.
In a container or VM where Chrome reports "No usable sandbox", set
AGENT_BROWSER_ARGS="--no-sandbox" for the capture command.
Never commit a screenshot to the repo
Git keeps every blob forever. A deleted PNG is still in history, still in every
clone, still counted against the repo size. Two screenshots run about 800 KB, so
one a week is tens of megabytes a year that nobody can ever reclaim without
rewriting history for everyone. This repo merges with merge commits rather than
squashing, so anything committed on a branch lands in main's history intact.
So: screenshots do not go in docs/, in the source tree, or anywhere under
version control.
A capture is a build artifact. Treat it like one.
Upload it instead
./scripts/publish-captures.sh before.png after.png # print the markdown
./scripts/publish-captures.sh --pr <n> before.png after.png # and append it to the PR
That posts each file to GitHub's attachment store, the same place a file dragged into a PR description ends up, and prints a markdown table to paste in. The images render inline, including on a private repo, and nothing is committed.
It needs nothing but an authenticated gh. No secret, no workflow, no branch.
Dragging the files into the PR description in a browser does exactly the same thing and is still fine when you are there anyway.
Why this works on a private repo when a link to a repo file does not
GitHub fetches a copy of every image in a PR body through a proxy that is not logged in as the reader. A URL pointing into a private repo gets refused, so the image is broken for everyone. Anything that does render from such a URL had to be publicly readable, which is why a bucket or a secret gist does not solve this, it only moves where the public copy lives.
Attachments are the exception: GitHub stores and serves them itself, so there is no fetch to fail, and access follows the repo.
The upload endpoint is POST https://uploads.github.com/user-attachments/assets
with a Bearer token. GitHub has not documented it, so if it starts returning 404
or 422, assume it changed and drag the files in by hand rather than debugging
the script.
Put it in the PR
The table goes in the PR body, not a comment, so it is the first thing a reviewer sees.
gh pr view --json number,body
gh pr edit <number> --body "<existing body>
## Before and after
| Before | After |
|:------:|:-----:|
|  |  |
"
When the proof is numbers instead of images:
## Before and after
| Metric | Before | After |
|---|---:|---:|
| `/api/items` p95 | 815 ms | 61 ms |
| DB queries per request | 43 | 2 |
Measured on the seeded test account, 20 records, same machine, 10 runs.
State the conditions. A number without conditions is not proof.
When the after does not match the claim
Look at the after capture before you post it. If it does not show the feature working, the change is not done. Go back and build, then capture again. Do not post a pair that shows the old behavior and describe it as fixed.
Errors
| Error | Fix |
|---|---|
command not found |
npm install -g @vercel/before-and-after |
could not determine executable |
Use the full name, npx @vercel/before-and-after |
| Element not found | Check the selector exists on the page |
| Blank screenshot on a protected route | Not logged in. Sign in as the test user first |
| Upload went to 0x0.st | You forgot IMAGE_ADAPTER=gist. Delete nothing, it cannot be deleted. Report it |