Skip to content

Commit f4e31a4

Browse files
nucliwebnucliweb
committed
chore(cli): release v0.2.0
Bump version to 0.2.0. Update README to document loading and audit workflows, all new options (--markdown, --viewport, --interact-script, --verbose), snippet aliases table, and revised Known Limitations and Roadmap sections.
1 parent 8c60691 commit f4e31a4

2 files changed

Lines changed: 64 additions & 17 deletions

File tree

‎cli/README.md‎

Lines changed: 63 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Run curated [WebPerf Snippets](https://webperf-snippets.nucliweb.net) headlessly
55
<img width="1820" height="1442" alt="webperf-snippets-CLI" src="https://github.com/user-attachments/assets/af7e6b02-8877-407e-87a4-db063468b5fb" />
66

77

8-
> **Status:** v0.1 (MVP). Core Web Vitals workflow only. See [Roadmap](#roadmap) for what's next.
8+
> **Status:** v0.2. Core Web Vitals, loading audit, and structural checks. See [Roadmap](#roadmap) for what's next.
99
1010
## Why
1111

@@ -38,6 +38,24 @@ Run the default Core Web Vitals workflow (LCP + CLS, plus LCP-Subparts if LCP >
3838
npx webperf-snippets https://web.dev
3939
```
4040

41+
Loading audit (TTFB, FCP, render-blocking, scripts, fonts):
42+
43+
```bash
44+
npx webperf-snippets https://web.dev --workflow loading
45+
```
46+
47+
Structural checks for CI (render-blocking, fonts, priority hints, resource hints):
48+
49+
```bash
50+
npx webperf-snippets https://web.dev --workflow audit
51+
```
52+
53+
Markdown output for PR comments:
54+
55+
```bash
56+
npx webperf-snippets https://web.dev --markdown
57+
```
58+
4159
JSON output (for piping into `jq` or CI):
4260

4361
```bash
@@ -50,6 +68,12 @@ Single snippet:
5068
npx webperf-snippets https://web.dev --snippet LCP-Subparts
5169
```
5270

71+
Synthetic INP measurement with an interaction script:
72+
73+
```bash
74+
npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
75+
```
76+
5377
CI gating:
5478

5579
```bash
@@ -58,16 +82,40 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
5882

5983
### Options
6084

61-
| Option | Description |
62-
| --------------------- | ---------------------------------------------------------- |
63-
| `--workflow <name>` | Workflow to run. Default: `core-web-vitals`. |
64-
| `--snippet <name>` | Run a single snippet (`LCP`, `CLS`, or `Category/Name`). |
65-
| `--json` | Output JSON instead of formatted text. |
66-
| `--wait <ms>` | Post-load wait before evaluating snippets. Default: `3000`.|
67-
| `--budget-lcp <ms>` | Exit `1` if LCP exceeds this value. |
68-
| `--budget-cls <score>`| Exit `1` if CLS exceeds this value. |
69-
| `--headed` | Show the browser window (debug). |
70-
| `-h, --help` | Show help. |
85+
| Option | Description |
86+
| ---------------------------- | ---------------------------------------------------------------------- |
87+
| `--workflow <name>` | Workflow to run. Default: `core-web-vitals`. Options: `core-web-vitals`, `loading`, `audit`. |
88+
| `--snippet <name>` | Run a single snippet by alias or `Category/Name` path. |
89+
| `--json` | Output JSON instead of formatted text. |
90+
| `--markdown` | Output GitHub-renderable markdown (for PR comments). |
91+
| `--viewport <preset>` | Viewport preset: `mobile` (default), `tablet`, `desktop`. |
92+
| `--wait <ms>` | Post-load wait before evaluating snippets. Default: `3000`. |
93+
| `--interact-script <path>` | JSON file with interactions to run before evaluation (for INP). |
94+
| `--budget-lcp <ms>` | Exit `1` if LCP exceeds this value. |
95+
| `--budget-cls <score>` | Exit `1` if CLS exceeds this value. |
96+
| `--verbose` | Show all items, including passing checks. |
97+
| `--headed` | Show the browser window (debug). |
98+
| `-h, --help` | Show help. |
99+
100+
### Snippet aliases
101+
102+
| Alias | Snippet |
103+
| ------------------ | ---------------------------------------------- |
104+
| `LCP` | CoreWebVitals/LCP |
105+
| `CLS` | CoreWebVitals/CLS |
106+
| `LCP-Subparts` | CoreWebVitals/LCP-Subparts |
107+
| `fonts` | Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold |
108+
| `render-blocking` | Loading/Find-render-blocking-resources |
109+
| `resource-hints` | Loading/Resource-Hints-Validation |
110+
| `preload-scripts` | Loading/Validate-Preload-Async-Defer-Scripts |
111+
| `priority-hints` | Loading/Priority-Hints-Audit |
112+
| `critical-css` | Loading/Critical-CSS-Detection |
113+
| `ttfb` | Loading/TTFB-Sub-Parts |
114+
| `script-parties` | Loading/First-And-Third-Party-Script-Info |
115+
| `script-loading` | Loading/Script-Loading |
116+
| `lazy-atf` | Loading/Find-Above-The-Fold-Lazy-Loaded-Images |
117+
| `lazy-conflict` | Loading/Find-Images-With-Lazy-and-Fetchpriority |
118+
| `eager-below-fold` | Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport |
71119

72120
### Exit codes
73121

@@ -115,17 +163,16 @@ Tag protection rules restrict who can push `cli-v*` tags. Configure them under *
115163

116164
The `NPM_TOKEN` secret must be set in the repository settings with publish access to the `webperf-snippets` npm package.
117165

118-
## Known limitations (v0.1)
166+
## Known limitations
119167

120-
- **No INP**: INP requires real user interactions. v0.2 will support synthetic interaction scripts.
121168
- **CLS in headless is conservative**: layout shifts that only happen on scroll are missed unless you script the scroll.
122169
- **First navigation only**: each `webperf-snippets` invocation runs one URL. SPAs need the post-route URL passed directly.
123-
- **Decision-tree follow-ups re-navigate**: when a follow-up snippet fires (e.g. LCP-Subparts), the page is loaded again. v0.2 will share a single page session.
170+
- **Synthetic INP ≠ field INP**: `--interact-script` measures handler latency for a single scripted event. Real INP reflects the worst interaction across all user sessions — use RUM for field data.
124171

125172
## Roadmap
126173

127-
- v0.2: Loading workflow (TTFB, FCP, render-blocking, scripts, fonts), shared page session, synthetic interactions for INP.
128-
- v0.3: Markdown reporter for PR comments, GitHub Action wrapper.
174+
- ~~v0.2: Loading workflow (TTFB, FCP, render-blocking, scripts, fonts), shared page session, synthetic interactions for INP, markdown reporter for PR comments.~~ ✓ Released
175+
- v0.3: GitHub Action wrapper.
129176
- v0.4: Auth flows (login + measure logged-in pages), CrUX field-data enrichment.
130177

131178
## How it works

‎cli/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "webperf-snippets",
3-
"version": "0.1.0",
3+
"version": "0.2.0",
44
"description": "Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes.",
55
"type": "module",
66
"bin": "./src/bin.js",

0 commit comments

Comments
 (0)