feat: add webperf-snippets CLI (MVP)#73
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Adds a headless CLI that runs curated WebPerf Snippets via Playwright, enabling Core Web Vitals diagnosis and CI budget gating without manual DevTools copy-paste. - npx webperf-snippets <url> runs LCP + CLS with human-readable output - --json, --snippet, --budget-lcp/cls, --headed, --wait flags - Decision tree: LCP > 2.5s auto-enqueues LCP-Sub-Parts - Runner shims performance.getEntriesByType for LCP/layout-shift entries (Chrome does not expose these via the API without a buffered observer) - Zero non-peer deps, requires Node >= 20.12, Playwright as peer dep - Root package renamed to webperf-snippets-docs; workspace added at cli/
Replace the hardcoded desktop viewport with named presets (mobile, tablet, desktop). Mobile (375×812) is now the default, matching real-world usage. The --viewport flag lets callers select a preset from the CLI.
Add Vitest as dev dependency with three test layers: - Unit tests for decision-tree, reporters (JSON and human), and viewport presets - E2E tests using Playwright against a local HTTP server to verify LCP and CLS snippets return valid results on a real browser session
Publish to npm on cli-v* tags via publish-cli.yml. The workflow runs the full test suite (unit + E2E) before publishing. Access is controlled via GitHub tag protection rules on the cli-v* pattern.
Adds --snippet fonts as a short alias for the Fonts-Preloaded-Loaded-and-used-above-the-fold snippet. Reporter now shows loaded fonts table (with font-display warnings for block/auto) and used-above-fold table, matching the detail level of the browser console output.
Introduces --workflow audit with 11 CI-safe snippets (Tier 1 loading + Tier 2 media) that return binary pass/fail results without timing noise. - New auditWorkflow with render-blocking, resource-hints, preload-scripts, priority-hints, critical-css, ttfb, script-parties, script-loading, lazy-atf, lazy-conflict, eager-below-fold - renderAuditResult reporter: shows issues with ✗/⚠/ℹ icons and items list - Exit code 1 when any audit snippet reports error-severity issues (CI gate) - 22 new snippet aliases (short + full names) - Add issues field to Find-render-blocking-resources return value - Fix LCP subparts renderer to not fire on TTFB-Sub-Parts (different schema) - E2E tests: green and violations fixtures covering 🟢🟡🔴 states
…I docs page - Add --verbose flag to show items for passing checks (default: hidden when green) - Fix critical-css items rendering empty bullet points by extending field name fallback chain to include item.filename and item.media - Add pages/CLI.mdx with install, usage, options, exit codes, CI integration - Add CLI section to homepage after AI Agent Skills - Update _meta.json to include CLI in navigation
- Update webperf skill schema references across .claude/skills and skills/ - Update Loading MDX pages (Back-Forward-Cache, Cache-Strategy-Analysis, Client-Side-Redirect-Detection, First-And-Third-Party-Script-Info, Resource-Hints-Validation, Validate-Preload-Async-Defer-Scripts) - Update First-And-Third-Party-Script-Info snippet - Update cli/README.md and reporters unit tests - Update README.md and public/llms-full.txt
…rces - Remove ### Overview section, intro paragraph goes directly under title - Replace 9 bold-as-headers with ### headings in sentence case - Fix 4 headings from title case to sentence case - Refactor JS snippet: calculate lastBlockingEnd, totalSizeBytes, byType once before if/else to eliminate duplicate computation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
webperf-snippets) that runs curated WebPerf Snippets via Playwright, enabling Core Web Vitals diagnosis and structural audits in CI without manual DevTools copy-paste.webperf-snippets-docs(private, no external impact);cli/added as npm workspace withname: webperf-snippets.Available snippets
LCPCLSLCP-Subpartsfontsrender-blockingresource-hintspreload-scriptspriority-hintscritical-cssttfbscript-partiesscript-loadinglazy-atflazy-conflictlazy+fetchpriorityconflicteager-below-foldWorkflows
Two built-in workflows selectable via
--workflow:core-web-vitals(default) — runsLCP+CLS, auto-enqueuesLCP-Subpartsif LCP exceeds 2.5 s.audit— deterministic structural checks (no timing noise) covering all Tier 1 Loading and Media snippets; designed for CI pass/fail gating.Usage
Files added / changed
cli/package.jsoncli/src/bin.jsutil.parseArgs, exit codes 0/1/2cli/src/runner.jscli/src/load-snippet.jsCategory/Namepathcli/src/workflows/cwv.jscli/src/workflows/audit.jscli/src/decision-tree.jscli/src/reporters/human.jsutil.styleTextcli/src/reporters/json.jscli/tests/unit/cli/tests/e2e/cli/tests/fixtures/cli/README.mdpages/CLI.mdx.github/workflows/ci.yml.github/workflows/publish-cli.ymlTest plan
node cli/src/bin.js --helpprints usagenode cli/src/bin.js https://web.devreturns green LCP + CLS with element infonode cli/src/bin.js https://web.dev --workflow auditruns all structural checksnode cli/src/bin.js https://web.dev --jsonreturns valid JSON with all fieldsnode cli/src/bin.js https://web.dev --snippet LCP-Subpartsshows sub-part breakdownnode cli/src/bin.js https://web.dev --snippet render-blockingshows blocking resourcesnode cli/src/bin.js https://web.dev --snippet fontsshows loaded/used-above-fold font tablesnode cli/src/bin.js https://web.dev --viewport desktopruns at desktop viewportnode cli/src/bin.js https://web.dev --budget-lcp 100exits 1 with violation on stderrnode cli/src/bin.js https://web.dev --verboseshows all items including passing checksnpm testincli/)