パッケージの選び方

svelte-vitals は svelte-vitals(CLI)、@svelte-vitals/vite(プラグイン + ライブダッシュボード)、@svelte-vitals/mcp(MCPサーバー)という3つのnpmパッケージに加えて、npmからはインストールしない2つのサーフェスで構成されています: リポジトリから直接参照して使うファーストパーティの GitHub Action である @svelte-vitals/action と、CLIがプロジェクト内に生成する SKILL.md ファイルである Agent Skills です。いずれも同じルールエンジンとスコアリングを共有していますが、読み取る対象とカバー範囲が異なります。ほとんどのプロジェクトでは複数を組み合わせて使うことになります。

各パッケージは独立してバージョン管理されており、共有ルールエンジンである @svelte-vitals/core にはそれぞれ自分の semver 範囲で依存しています。そのため「同時に」インストールした2つのパッケージが、実際には異なる core バージョンに解決されることがあります — CLI と Vite プラグインで検出結果が食い違う場合はライブダッシュボード § バージョンのずれを参照してください。

早見表

やりたいこと	使うもの
プロジェクト全体のSEO・パフォーマンス・コードヘルスをCI/PRでゲートしたい	CLI — `npx svelte-vitals@latest`
コミットしようとしているファイルだけをチェックしたい	CLI(`--staged` / `--diff`)
GitHubのPRをインラインアノテーション・ジョブサマリー・スティッキーコメントでゲートしたい	GitHub Action — `npx svelte-vitals@latest ci install`
実際に配信されるHTMLそのものを、生成元に関わらず正確に検証したい	Vite プラグイン(ビルドモード)
ビルドを待たずに、開発中にプロジェクト全体をライブで確認したい	Vite プラグイン(ライブダッシュボード)
AIコーディングエージェント(Claude Code / Cursor / Codex)に自分の変更をチェックさせたい	MCPサーバー
コードを書く前からエージェントにルールを教える、または改善ロードマップを作らせたい	Agent Skills — `/svelte-vitals`・`/improve-svelte`

比較

	CLI (`svelte-vitals`)	Vite プラグイン — ビルドモード	Vite プラグイン — ライブダッシュボード	MCPサーバー
読み取る対象	ソース(`.svelte`ファイル、レイアウトチェーン)	プレレンダリング済みHTML出力 + `.svelte`ソース(コンポーネントルール)	起動時はソース、訪問済みルートはレンダリング済みHTML	ソース(CLIと同じエンジン)
カテゴリ	全5種 — SEO・Performance・Correctness・Security・Architecture	全5種 — SEO・Performance・Correctness・Security・Architecture	全5種(静的ベースライン)、訪問済みルートはレンダリング済みSEO/Performanceの精度に精緻化	全5種
対象ルート	全ルート(SSR・動的・プレレンダリング)	プレレンダリングされたルートのみ	起動時から全ルート — 訪問済みルートは `measured` に格上げ	全ルート
実行タイミング	任意 — ターミナル・CI・pre-commit	`vite build` の都度	`vite dev` 実行中にライブ	任意 — エージェントのツール呼び出し
ビルドが必要か	不要	必要	不要	不要
主な用途	CI・pre-commitフック・単発の監査	ビルドパイプラインのゲート	ローカル開発中のフィードバック(デフォルトで有効)	AIエージェントのツールループ

この表に意図的に載せていないサーフェスが2つあります: GitHub Action はCLI自身のエンジンをインプロセスで実行するため、カバー範囲はCLIの列そのものです — 追加されるのは異なる解析ではなく、PR体験(アノテーション・サマリー・スティッキーコメント)です。Agent Skills は自前の解析を一切行いません — エージェントにルールの知識と、いつスキャナーを実行すべきかを教えるものです。

なぜビルドモードのカバー範囲はCLIに近いのか

Correctness・Security・Architecture のルールはコンポーネントのソースコード($effectの中身、{@html}の呼び出し、propsの数など)を読み取りますが、これらはコンパイル前にしか存在しません。CLI、MCP(CLI自身の解析エンジンをそのまま呼び出す)、Vite プラグインのビルドモード、そしてライブダッシュボードの静的ベースラインはいずれもソースを直接読むため、この4つすべてが全5カテゴリのルールセットを実行できます。

実際にdevでルートを訪問すると、ダッシュボードはさらにそのルートのレンダリング済みHTMLを(svelteVitalsHandle 経由で)SEO/Performanceについて再チェックします — カバーする範囲においてはライブラリ非依存かつ正確です:何が <head> を生成したかに関わらず、実際に配信されるHTMLに欠けていればそれを検出します。この訪問済みルートのレンダリング済み再チェックだけが、ダッシュボードの静的ベースライン単体では得られないものです。ビルドモードも同じ理由でレンダリング済みHTMLを読み取りますが、それに加えてソーススキャンも行う唯一のビルド時経路です。

各パッケージの特徴

CLI — 最も広いカバー範囲

svelte-vitals はプロジェクトのソースを直接読むため、全ルート(SSR・動的ルートを含む)と全5カテゴリをカバーできる唯一の経路です。ビルド不要で、Node が動く環境ならどこでも実行できます — ターミナル、CIジョブ、--staged によるpre-commitフック、--diff main によるPRチェックなど。CIゲートを組むならまずここから。詳細は CLIリファレンスを参照してください。

Vite プラグイン — 正確なビルド時検証

@svelte-vitals/vite のビルドモードは vite build 実行中にSEO/Performance検証として実際にプレレンダリングされたHTMLを解析するため、ソーススキャナーが認識しないコンポーネントにごまかされることがありません — タグが出力HTMLに存在しなければ、それだけで検出されます。それに加えて .svelte ソースも直接走査し、CLIと同じ Correctness・Security・Architecture、およびコンポーネントスコープの2つの Performance ルールも検証します。残るトレードオフはルートの範囲です — HTMLベースのSEO/Performance検証はプレレンダリングされたルートのみが対象です(コンポーネントスコープのルールはプロジェクト全体が対象)。詳細はプラグインモードを参照してください。

同じパッケージは vite dev 中に /__svelte-vitals/ でライブダッシュボードもデフォルトで配信しており、ビルド不要で、起動時からプロジェクト全体をカバーし、ブラウジングに応じて実際のレンダリング結果に精緻化されます。これはゲートではなくフィードバックです — ビルドやCIを失敗させることはありません。詳細はライブダッシュボードを参照してください。

MCPサーバー — AIエージェントのワークフロー向け

@svelte-vitals/mcp はCLIそのものの解析(全5カテゴリ・全ルート)を analyze と explain_rule というModel Context Protocolのツールとして公開します。エージェントはCLIをシェルアウトしてテキスト出力をパースする代わりに、会話の途中で直接呼び出せます。AIコーディングエージェントを日常的に使っているなら有用ですが、CIゲートの代わりにはなりません。npx svelte-vitals@latest install でセットアップできます。詳細は MCPサーバーを参照してください。

GitHub Action — YAMLを書かずにPRをゲートする

@svelte-vitals/action はプルリクエストごとにCLIと同じエンジンを実行し、検出結果をGitHubネイティブなフィードバックに変換します: 変更行へのインラインアノテーション、ジョブサマリー、その場で更新される単一のスティッキーPRコメントです。npmからインストールするものではありません — npx svelte-vitals@latest ci install(または svelte-vitals install 内の ci-workflow ターゲット)がコミットSHAでピン留めした呼び出しを含むワークフローを生成し、後から svelte-vitals ci upgrade でそのピンを更新できます。生成されるワークフローは --diff/--baseline で検出結果をそのPR自身の変更分に絞るため、既存の問題が他の人のPRを失敗させることはありません。詳細は CI 連携を参照してください。

Agent Skills — エージェントに前もってルールの知識を

MCPサーバーがエージェントに解析を「実行させる」ものだとすれば、Agent Skills はエージェントが「コードを書く前からルールを知っている」状態を作るものです。svelte-vitals install は Claude Code・Codex・Cursor で同一に動作する可搬性のある SKILL.md を2つ生成します: /svelte-vitals はルールカタログ全体と「編集のたびにスキャナーを実行する」プレイブックを埋め込み、/improve-svelte は「アプリをレビューして」という依頼を影響度順の自己完結型実装プランに変える読み取り専用の監査です。MCPサーバーを置き換えるのではなく補完します — 知識は前もって、解析は必要なときに。詳細は Agent Skills を参照してください。