WebPerf Snippets

webperf-snippets CLI

厳選された WebPerf Snippets を、Playwright を使ってヘッドレスで実行します。Lighthouse で把握できる範囲を超えて Core Web Vitals を診断し、実際のパフォーマンス予算に基づいて CI の実行を制御します。

ステータス： v0.4。Core Web Vitals、読み込み、インタラクション、構造の監査ワークフローに対応し、コレクション内のすべてのスニペットを名前で指定できます。ロードマップをご覧ください。

理由

Lighthouse ではスコアが得られます。DevTools のスニペットでは、TTFB／リソース読み込み遅延／要素の描画遅延の各内訳、LoAF のスクリプト帰属、レンダリングをブロックするリソースなど、診断情報が得られます。この CLI は、同じ厳選スニペットをヘッドレスブラウザーで実行するため、次のことができます。

• DevTools にコピー＆ペーストせずに、CI で LCP のリグレッションを診断できます。
• 実際のパフォーマンス予算に基づいて、プルリクエストの実行を制御できます。
• 手動で実行しているスニペットを自動化できます。

インストール

Playwright はピア依存関係です。Chromium ブラウザーも含めて、両方をインストールしてください。

npm install --save-dev webperf-snippets playwright
npx playwright install chromium

使い方

npx webperf-snippets <url> [options]

例

デフォルトの Core Web Vitals ワークフローを実行します（LCP + CLS、LCP が 2.5s を超える場合は LCP-Subparts も実行します）。

npx webperf-snippets https://example.com

読み込みの監査（11 ステップ：TTFB、FCP、レンダリングをブロックする要素、スクリプト、リソースのタイミング、サードパーティの影響、フォント、キャッシュ。項目一覧はCLI のページにあります）。

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

CI 用の構造チェック（22 項目：レンダリングをブロックする要素、圧縮、フォント、画像、ヒント、DOM サイズなど。項目一覧はCLI のページにあります）。

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

PR コメント用の Markdown 出力：

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

JSON 出力（jq または CI にパイプする場合）：

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

単一のスニペット：

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

操作スクリプトを使った合成 INP の測定：

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

Interaction スニペット（Interactions、Input-Latency-Breakdown、LongTask、Forced-Synchronous-Layout など）は最初のステップの前にインストールされ、最後のステップの後に読み取られるため、その結果には各ステップによって引き起こされた内容が反映されます。

CLI は、最後の操作のタイミングがブラウザーから報告されてからスニペットを読み取ります。クリックの直後に終了するスクリプトでは、リクエストやアニメーションなど、クリックによって後から開始される処理が起きる前にページを読み取ってしまいます。そうした処理も測定したい場合は、最後に wait ステップを入れてください。

操作の監査（長いタスク、長いアニメーションフレーム、スクロール、レイアウトシフト、強制レイアウト、操作のレイテンシー）。ページをスクロールするか、--interact-script を実行します。クリックが必要なステップは、スクリプトにクリックがない場合はスキップされます。

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

Playwright のストレージ状態（Cookie と 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

このファイルには有効なセッション Cookie が含まれます。バージョン管理の対象から除外し（.gitignore に追加してください）、CI で実行するときは使い捨てアカウントを使用してください。パスが存在しない場合、CLI はコード 2 で終了します。

測定値を CrUX のフィールドデータ（実ユーザーの体験を示す 75 パーセンタイル値）と比較します。

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)

Chrome UX Report API のキーを取得し、--crux-key または CRUX_API_KEY 環境変数で渡してください。フラグはシェルの履歴や CI のログに残るため、環境変数を推奨します。このセクションは、人間向けおよび Markdown の出力と、--json 出力の crux の下に表示されます。

• 対象ユーザー層は --viewport に従います。desktop ではデスクトップのデータを使用し、mobile と tablet ではスマートフォンのデータを使用します。見出しにどちらのデータかが表示されます。
• ページ自体のデータがない場合、CLI は代わりにオリジンを検索し、このセクションに origin-level と表示します。これにより、ページ単位のデータと誤認されません。オリジンにもデータがない場合は、出力に Field data: not available と表示されます。
• CrUX エラー（クォータ超過、ネットワークエラー、10 秒以内に応答がない場合）が発生しても、このセクションだけがスキップされます。終了コードには影響せず、キーが出力されることもありません。
• 操作スクリプトを実行しない場合、INP の合成値は n/a と表示されます。

実行後に --report-to を使って結果をエンドポイントに送信します。

npx webperf-snippets https://example.com --workflow audit \
  --report-to https://reports.example.com/api/report \
  --api-key $REPORT_API_KEY

--report-to を指定しない場合、CLI は外部への呼び出しを行いません。指定した場合は、スニペットの処理が完了すると結果が JSON として POST されます。

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

--snippet を実行した場合、workflow は null になり、snippet フィールドに名前が入ります。results は --json 出力と同じリストで、測定したページの URL や詳細が含まれる場合があります。信頼できるエンドポイントにのみ送信してください。

• URL は https である必要があります。http が許可されるのは localhost のみです。これにより、キーが暗号化されずに送信されることはありません。
• --api-key は Authorization: Bearer <key> として送信されます。フラグはシェルの履歴や CI のログに残るため、PERF_REVIEWS_API_KEY 環境変数を推奨します。キーが出力されることはありません。
• 終了コードはレポートの成否に左右されません。POST に失敗した場合（エラーステータス、エンドポイントに到達できない、5 秒以内に応答がない）は警告が出力されますが、終了コードは引き続き予算とスニペットの結果によって決まります。エンドポイントが { "ok": false, "regressions": [...] } を返した場合も、終了コードは変わらず、リグレッションが警告として出力されます。

CI でのゲート設定：

npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1

オプション

オプション	説明
--workflow <name>	実行するワークフロー。デフォルト：core-web-vitals。選択肢：core-web-vitals、loading、audit、interaction。
--snippet <name>	名前、エイリアス、または Category/Name パスで指定した単一のスニペットを実行します。
--json	整形済みテキストの代わりに JSON を出力します。
--markdown	GitHub で表示可能な Markdown を出力します（PR コメント用）。
--viewport <preset>	ビューポートのプリセット：mobile（デフォルト）、tablet、desktop。
--wait <ms>	ページ読み込み後、スニペットを評価するまでの待機時間。デフォルト：3000。
--interact-script <path>	ページ読み込み後に実行する操作（scroll、click、hover、type、wait）を記述した JSON ファイル。Interaction スニペットが先にインストールされ、その後に読み込まれます。
--storage-state <path>	認証が必要なページ用の Playwright ストレージ状態（Cookie と localStorage）。
--crux-key <key>	測定値の横に CrUX のフィールドデータ（p75）を追加します。CRUX_API_KEY の使用を推奨します。
--report-to <url>	実行後、結果をこの https URL に POST します。これを指定しない限り、外部への呼び出しは行われません。
--api-key <key>	--report-to とともに Bearer トークンとして送信されます。PERF_REVIEWS_API_KEY の使用を推奨します。
--budget-lcp <ms>	LCP がこの値を超えた場合、1 で終了します。
--budget-cls <score>	CLS がこの値を超えた場合、1 で終了します。
--verbose	合格したチェックを含む、すべての項目を表示します。
--headed	ブラウザーウィンドウを表示します（デバッグ用）。
-h, --help	ヘルプを表示します。

スニペットのエイリアス

エイリアス	スニペット
LCP	CoreWebVitals/LCP
CLS	CoreWebVitals/CLS
INP	CoreWebVitals/INP
LCP-Subparts	CoreWebVitals/LCP-Subparts
fonts	Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold
render-blocking	Loading/Find-render-blocking-resources
resource-hints	Loading/Resource-Hints-Validation
preload-scripts	Loading/Validate-Preload-Async-Defer-Scripts
priority-hints	Loading/Priority-Hints-Audit
critical-css	Loading/Critical-CSS-Detection
ttfb	Loading/TTFB-Sub-Parts
script-parties	Loading/First-And-Third-Party-Script-Info
script-loading	Loading/Script-Loading
lazy-atf	Loading/Find-Above-The-Fold-Lazy-Loaded-Images
lazy-conflict	Loading/Find-Images-With-Lazy-and-Fetchpriority
eager-below-fold	Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport

フォローアップ手順

実行結果に応じて、同じページ読み込みで手順が追加されます。LCP が 2.5 秒を超えると LCP-Subparts、4 秒を超えると LCP-Trail が追加されます。画像または動画が LCP の場合は、そのエントロピー、画像または動画の監査が追加されます。CLS が 0.1 を超えると Layout-Shift-Loading-and-Interaction、0.25 を超えると、遅延読み込み画像、フォント、クリティカル CSS、寸法のない画像も追加されます。TTFB が 600 ミリ秒を超えると TTFB-Sub-Parts、FCP が 1.8 秒を超えるとレンダリングをブロックする要素のチェックが追加されます。全表はCLI ページにあります。各スニペットは 1 回だけ実行され、フォローアップ結果が通知されます。その error による問題は終了コードを変更しません。

終了コード

コード	意味
0	すべてのチェックに合格しました。
1	予算違反、スニペットのエラー、またはワークフローの手順で error の問題が報告されました。
2	使用方法のエラー（URL がない、ワークフローが不明）。

MCP サーバー

webperf-snippets mcp は、stdio 経由で Model Context Protocol サーバーを起動します。AI エージェントはソースを読む代わりに、名前を指定してスニペットを呼び出せます。Claude Code など、ローカルサーバーを起動するクライアントに追加してください。

claude mcp add webperf -- npx -y webperf-snippets mcp

Playwright の Chromium が必要です（npx playwright install chromium）。インストールされていない場合、ツールはそのコマンドを返します。MCP サーバーのドキュメントには、ほかのクライアント（Cursor、VS Code、Claude Desktop、Gemini CLI）の設定が記載されています。このサーバーは、io.github.nucliweb/webperf-snippets として MCP Registry に登録されています。

ツール	説明
list_snippets	カテゴリー、タイトル、短縮エイリアス、インタラクションを追跡するかどうかとともに、スニペットの一覧を返します。category は任意です。
run_snippet	ヘッドレス Chromium で URL を開き、1 つのスニペットを実行して、その戻り値を返します。url、snippet（名前、エイリアス、または Category/Name）、任意の viewport と waitMs を指定します。インタラクションを記録するスニペットは、open_page で開いたページ上で実行されます。
run_workflow	CLI のワークフロー（core-web-vitals、audit、loading、interaction）と、その判断ツリーの後続処理を実行します。url、workflow、任意の viewport と waitMs を指定します。
get_crux	URL またはそのオリジンの LCP、CLS、INP の CrUX p75 を返します。url と任意の formFactor（phone、desktop、tablet）を指定します。サーバーの環境変数に CRUX_API_KEY が必要です。
open_page	呼び出しの間も開いたままになるページで URL を開き、トラッキングスニペット（INP などの track）をインストールします。sessionId を返します。
interact	開いているページで、click、type、hover、scroll、wait の各ステップを実行します。
read_results	開いているページのトラッキングスニペットが記録した内容を返します。
close_page	開いているページを閉じます。

このサーバーはリソースも提供します。クライアントはこれらのドキュメントをコンテキストに追加できます。

リソース	内容
webperf://schema	すべてのスニペット結果が従う仕様です。基本構造、ステータス、結果の読み方を記載しています。
webperf://schema/{snippet}	1 つのスニペットが返すフィールドと、その例を記載しています。
webperf://workflows/{category}	カテゴリーのワークフローと判断ツリーを記載しています。

さらに、ツールを連鎖させるテンプレートであるプロンプトも提供します（Claude Code では /mcp__webperf__audit_lcp）。audit_lcp、debug_inp、audit_page の各プロンプトには、それぞれ url 引数があります。

CrUX キーはクライアントの設定に記述してください。ツールの引数には決して指定しないでください。

claude mcp add webperf -e CRUX_API_KEY=<key> -- npx -y webperf-snippets mcp

同時に開けるページは最大 3 つです。10 分間使用されなかったページは閉じられ、クライアントが切断されると、すべてのページと Chromium が閉じられます。

このサーバーは、2026-07-28 のリビジョンと、initialize で開始する以前のリビジョンの、両方のプロトコルに対応するクライアントに応答します。ADR 0002 では、なぜサブコマンドとして stdio を使用するのかを説明しています。

CI の例

GitHub Actions で、LCP が 2.5 秒を超えた場合に PR を失敗させます。

- run: |
    npm install --no-save webperf-snippets playwright
    npx playwright install --with-deps chromium
    npx webperf-snippets https://staging.example.com --budget-lcp 2500 --budget-cls 0.1

GitHub Action

このリポジトリには、CLI と Chromium をインストールし、ワークフローを実行して、結果を Markdown として公開するコンポジットアクションが含まれています。これにより、追加の設定なしで、どのリポジトリでもパフォーマンス予算に基づくゲートを設定できます。

jobs:
  webperf:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: nucliweb/webperf-snippets/.github/actions/webperf-snippets@main
        id: webperf
        with:
          url: https://staging.example.com
          budget-lcp: 2500
          fail-on-budget: "false"

      - uses: actions/github-script@v7
        env:
          BODY: ${{ steps.webperf.outputs.markdown }}
        with:
          script: |
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: process.env.BODY,
            });

      - if: steps.webperf.outputs.exit-code != '0'
        run: exit 1

入力	デフォルト	説明
url	必須	測定する URL です。
workflow	core-web-vitals	実行するワークフローです：core-web-vitals、loading、audit、または interaction。
budget-lcp	2500	LCP の予算（ミリ秒）です。空の値にするとチェックが無効になります。
budget-cls	0.1	CLS の予算です。空の値にするとチェックが無効になります。
fail-on-budget	true	予算超過またはスニペットのエラー時にステップを失敗させます。"false" を指定すると、exit-code を読み取って独自に判断できます。
cli-version	latest	実行する webperf-snippets npm パッケージのバージョンです。

出力	説明
markdown	結果を Markdown 形式で返します。ジョブのサマリーにも書き込まれます。
exit-code	CLI の終了コードです：0 は合格、1 は予算超過またはスニペットのエラー、2 は使用方法のエラーです。

Markdown には測定したページから取得したテキストが含まれるため、上記のように環境変数（env: と process.env）を通じて他のステップに渡してください。スクリプト内で ${{ steps.webperf.outputs.markdown }} を補間してはいけません。fail-on-budget: "false" の場合、アクションのステップは常に成功するため、ジョブが失敗する前に後続のステップでコメントを投稿できます。permissions: pull-requests: write がない場合、コメントのステップはプルリクエストに投稿できません。

共有ランナーでは LCP、CLS、INP が 15～30% 変動します。ゲートには、より決定論的な audit ワークフローを使用するか、余裕のある予算を設定してください。

公開

CLI パッケージは、タグベースのワークフローを通じて npm に公開されます。公開は明示的かつ意図的に行われ、cli-v* タグがプッシュされた場合にのみ実行されます。

リリース手順

1. cli/package.json のバージョンを更新します。
2. バージョン変更をコミットします。
3. タグを付けてプッシュします：

   git tag cli-v0.2.0
   git push origin cli-v0.2.0
   

4. publish-cli CI ジョブが実行され、テストスイート全体を実行した後、npm に公開します。

パスベースではなくタグベースにする理由

代替案として、cli/ に変更がある main へのプッシュごとに、バージョンを確認して再公開をスキップしながら自動公開する方法があります。タグベースの公開が選ばれたのは、リリースを意図的に行えるためです。main で CI が成功しても、パッケージをリリースする準備ができているとは限りません。また、タグによってその意図を明確に示せます。

アクセス制御

タグ保護ルールにより、cli-v* タグをプッシュできるユーザーを制限します。リポジトリの Settings → Rules → New ruleset で設定し、cli-v* のタグパターンを対象にして、プッシュ権限を管理者またはメンテナーに限定してください。これにより、許可されたコラボレーターのみが公開を実行できます。

必須のシークレット

NPM_TOKEN シークレットを、webperf-snippets npm パッケージへの公開アクセス権を付与した状態で、リポジトリの設定に登録する必要があります。

既知の制限事項

• ヘッドレスモードでの CLS は保守的です：スクロール時にのみ発生するレイアウトシフトは、スクロールをスクリプトで実行しない限り検出されません。
• 最初のナビゲーションのみ：各 webperf-snippets の呼び出しで実行できる URL は 1 つです。SPA では、ルート変更後の URL を直接渡す必要があります。
• 合成 INP ≠ 実環境の INP：--interact-script は、スクリプトで実行した単一イベントのハンドラー遅延を測定します。実際の INP は、すべてのユーザーセッションにおける最悪のインタラクションを反映します。実環境のデータには RUM を使用してください。

ロードマップ

• v0.2：読み込みワークフロー（TTFB、FCP、レンダリングを妨げる要素、スクリプト、フォント）、共有ページセッション、INP 用の合成インタラクション、PR コメント用の Markdown レポーター。 ✓ リリース済み
• v0.3：GitHub Action ラッパー、認証フロー（ログインとログイン済みページの測定）、CrUX の実環境データによる拡充、--report-to。 ✓ リリース済み
• v0.4：名前による各スニペットの実行、22 ステップの監査、11 ステップの読み込みワークフロー、Core Web Vitals のインタラクションワークフローと決定木による追加調査。 ✓ リリース済み

仕組み

1. Playwright を使ってヘッドレスの Chromium を起動します。
2. URL に移動し、load イベントを待ってから --wait ミリ秒（デフォルトは 3000 ミリ秒）待機し、遅れて記録されるエントリーがページに反映されるようにします。
3. 各スニペットの IIFE をページのコンテキストで評価し、返されたオブジェクトを取得します。スニペットは、Chrome がオブザーバーにのみ公開するエントリー（LCP、レイアウトシフト、長時間タスク、イベントタイミング）をバッファリングされた PerformanceObserver で読み取るため、実行前に記録されたエントリーも取得できます。
4. インタラクションスクリプトを指定した場合は、まずトラッキング用スニペットをインストールし、インタラクションを実行してページが落ち着くまで待機します。その後、トラッキングデータを読み取り、残りのスニペットを実行します。
5. ワークフローの決定木を適用し、追加調査用のスニペットをキューに追加します。
6. 結果を（人間向けまたは JSON 形式で）出力し、適切な終了コードで終了します。

ライセンス

MIT。詳しくは LICENSE をご覧ください。