WebPerf Snippets

webperf-snippets CLI

Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes and gate CI on real performance budgets.

Status: v0.4. Core Web Vitals, loading, interaction and structural audit workflows, and every snippet of the collection by name. See the Roadmap.

Why

Lighthouse gives you a score. The DevTools snippets give you the *diagnosis*, such as TTFB / Resource Load Delay / Element Render Delay sub-parts, LoAF script attribution, and render-blocking resources. This CLI runs the same curated snippets in a headless browser so you can:

• Diagnose LCP regressions in CI without copy-pasting into DevTools.
• Gate pull requests on real performance budgets.
• Automate the snippets you already run by hand.

Install

Playwright is a peer dependency. Install both, plus the chromium browser:

npm install --save-dev webperf-snippets playwright

npx playwright install chromium

Usage

npx webperf-snippets <url> [options]

Examples

Run the default Core Web Vitals workflow (LCP + CLS, plus LCP-Subparts if LCP > 2.5s):

npx webperf-snippets https://example.com

Loading audit (11 steps: TTFB, FCP, render-blocking, scripts, resource timings, third-party impact, fonts, cache; the list is in the CLI page):

npx webperf-snippets https://example.com --workflow loading

The steps that tell first-party from third-party resources count as first party the root domain of the page and its subdomains (cdn.example.com for example.com). A site that serves its own assets from another domain, such as its CDN, lists it with --own-domains, comma-separated or repeated:

npx webperf-snippets https://example.com --workflow loading --own-domains cdn.example.net,static.example.org

Each domain counts with its root domain, so cdn.example.net makes every host under example.net first party. The CLI writes the list in the OWN_DOMAINS constant of each snippet, the same one you edit at the top of the snippet in the console. An empty domain or one with spaces exits with code 2.

Structural checks for CI (22 checks: render-blocking, compression, fonts, images, hints, DOM size and more; the list is in the CLI page):

npx webperf-snippets https://example.com --workflow audit

Markdown output for PR comments:

npx webperf-snippets https://example.com --markdown

JSON output (for piping into jq or CI):

npx webperf-snippets https://example.com --json

The JSON output records how the page was measured in conditions, so a later run can tell whether it measured the same way: the viewport, the workflow (or the path of the snippet with --snippet), the wait, the version of the CLI and the machine: its CPU model, cores, architecture and memory, as the operating system reports them, and a benchmark index, a short CPU test in Node before Chromium starts, which only informs, since on the same machine it moves by up to 40 % with the load.

"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.12.0", "machine": { "cpu": "Apple M4", "cores": 10, "arch": "arm64", "memoryGB": 16, "benchmarkIndex": 2371 } }

Single snippet:

npx webperf-snippets https://example.com --snippet LCP-Subparts

Synthetic INP measurement with an interaction script:

npx webperf-snippets https://example.com --snippet INP --interact-script interactions.json

npx webperf-snippets https://example.com --snippet Interaction/Interactions --interact-script interactions.json

The Interaction snippets (Interactions, Input-Latency-Breakdown, LongTask, Forced-Synchronous-Layout...) are installed before the first step and read after the last one, so their result holds what the steps caused.

The CLI waits for the browser to report the timing of the last interaction before it reads the snippets. A script that ends right after a click still reads the page before anything the click sets in motion later has happened, such as a request or an animation, so end it with a wait step when you want to measure that.

Interaction audit (long tasks, long animation frames, scroll, layout shifts, forced layouts, interaction latency). It scrolls the page, or runs your --interact-script; the steps that need a click are skipped when the script has none:

npx webperf-snippets https://example.com --workflow interaction

Pages behind a login, with a Playwright storage state (cookies and localStorage):

# Step 1: sign in once and save the session

npx playwright codegen --save-storage=auth.json https://example.com/login

Step 2: measure an authenticated page

npx webperf-snippets https://example.com/dashboard --storage-state auth.json

The file holds live session cookies. Keep it out of version control (add it to .gitignore) and use a throwaway account when you run it in CI. The CLI exits with code 2 if the path does not exist.

Pages behind an access proxy that reads a token from every request, such as the service tokens of Cloudflare Access, take the token as request headers with --header, once per header:

npx webperf-snippets https://review.example.com \

--header "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \ --header "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

The headers go with every request to the origin of the URL and never to another origin, so third parties do not receive the token and their cross-origin requests need no CORS preflight. Each request to that origin is paused in the browser to add them, which adds a few milliseconds to its timing; when the proxy accepts a session cookie, --storage-state measures without that cost. A header without a name or a colon exits with code 2. Read the values from environment variables, as above, to keep them out of the shell history.

Compare the measured values with CrUX field data (what real users experience at the 75th percentile):

CRUX_API_KEY=your-key npx webperf-snippets https://example.com

Field data (CrUX p75, mobile)

🟡 LCP 2.80s needs-improvement (synthetic: 2.10s) 🟢 CLS 0.0800 good (synthetic: 0.0500) 🟡 INP 220ms needs-improvement (synthetic: n/a)

Get a key for the Chrome UX Report API and pass it with --crux-key or the CRUX_API_KEY environment variable; prefer the variable, because a flag ends up in shell history and CI logs. The section appears in the human and markdown output and under crux in the --json output.

With a key, the field data also gives what CrUX knows of the LCP when it is an image: the p75 of its sub-parts, TTFB, load delay, load duration and render delay. When the measurement ran LCP-Subparts, with --snippet LCP-Subparts or the core-web-vitals workflow over 2.5 s, a table puts each one next to its lab value, with a note where one side is at least 1.5 times the other and 100 ms apart: a slower server or network for users, an image the lab finds sooner, slower connections, slower devices, or a lab slower than users. The field sub-parts describe only the loads whose LCP is an image, and the table says which share that is; when the LCP of the lab is not an image, only TTFB and render delay compare. Each p75 is taken on its own, so the sub-parts do not add up to the p75 of LCP. A line gives the navigation types of the users, by share, and points to Back-Forward-Cache when over 5 % of the visits come back without the back/forward cache. The JSON output carries them in crux.subParts, crux.lcpImageShare, crux.roundTripTime and crux.navigationTypes.

--crux-history adds the trend of the field data over the last 1 to 40 weeks, from the CrUX History API, with the same key. Each week is the p75 of the 28 days before it, so the weeks overlap and the series is smooth. For LCP, CLS and INP the section gives the first and the last week, the change between them and its direction, stable within 5 %, and the weeks as a sparkline, where a gap is a week with too little data. The bars span at least the smallest change --baseline counts for the metric (100 ms for LCP, 50 ms for INP, 0.05 for CLS), so a series that barely moves draws almost flat:

Field data trend (CrUX p75, 40 weeks, mobile, origin-level)

LCP 2.88s → 3.10s ▲ +7.7% worsening ▃▃▄▃▃▃▄▆▇██▇▆▄▂▁▂▃▃▄▅▆▆▆▆▆▆ CLS 0.2600 → 0.2100 ▼ −19.2% improving ▅▆▆▇▇█▇▆▆▅▄▃▃▃▃▃▂▂▁▂▂▂▂▂▂▂ INP 253ms → 251ms ▼ −0.8% stable ▅▅▅▄▄▄▅▅▆▆▆▅▅▄▄▄▄▅▅▅▅▄▄▄▃▃▄▄▄▅▅

The JSON output carries it in crux.history, with the periods, the p75 of each week and the trend of each metric. Like the p75, it uses the page when it has data of its own and its origin otherwise, and says which in scope.

• The population follows --viewport: desktop uses desktop data, mobile and tablet use phone data. The heading says which one.
• When the page itself has no data, the CLI looks the origin up instead and labels the section origin-level, so it is not mistaken for page-level data. If the origin has none either, the output says Field data: not available.
• A CrUX error (quota, network, no answer within 10 seconds) only skips the section. It never changes the exit code, and the key is never printed.
• INP shows n/a as the synthetic value unless you run an interaction script.

Send the results to an endpoint after the run with --report-to:

npx webperf-snippets https://example.com --workflow audit \

--report-to https://reports.example.com/api/report \ --api-key $REPORT_API_KEY

Without --report-to the CLI makes no external calls. With it, the results are POSTed as JSON once the snippets have finished:

{

"url": "https://example.com", "workflow": "audit", "timestamp": "2026-05-06T10:00:00.000Z", "navMs": 1240, "results": [], "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.12.0" } }

For a --snippet run, workflow is null and a snippet field carries the name. With --cpu or --network, meta carries the conditions in throttling, and with --runs, the summary of the runs in runs. results is the same list the --json output contains, so it can include URLs and details of the measured page; send it only to an endpoint you trust.

• The URL must be https. http is accepted only for localhost, so a key is never sent in clear text.
• --api-key is sent as Authorization: Bearer . Prefer the PERF_REVIEWS_API_KEY environment variable, because a flag ends up in shell history and CI logs. The key is never printed.
• The exit code never depends on the report. A failed POST (error status, unreachable endpoint, or no answer within 5 seconds) prints a warning and the exit code stays the one the budgets and snippets decide. If the endpoint answers { "ok": false, "regressions": [...] }, the regressions are printed as a warning, again without changing the exit code.

Measure under the conditions of a slower device and network with --cpu and --network. Without them the CLI runs at the speed of the machine, which on a laptop or a CI runner is faster than most phones:

npx webperf-snippets https://example.com --cpu 4 --network slow-4g

--cpu slows the main thread down by that factor. --network takes the presets of DevTools, with the same values:

| slow-4g | 1.44 Mbps | 675 kbps | 5