パッケージの選び方
svelte-vitals のどのパッケージ（CLI、Vite プラグイン、GitHub Action、Agent Skills）をいつ使い、どう組み合わせるか。
npm パッケージは svelte-vitals（CLI）と @svelte-vitals/vite（プラグイン + ライブダッシュボード）の2つです。npm からインストールしないものも2つあります。リポジトリから直接参照する GitHub Action の @svelte-vitals/action と、skills.sh から npx skills add でインストールする SKILL.md の Agent Skills です。
CLI・プラグイン・Action は同じルールエンジンとスコアリングを共有し、読み取る対象だけが異なります。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）に自分の変更をチェックさせたい | CLI の --diff --reporter agent |
| 導入時にエージェントに設定を導出させる、改善ロードマップを作らせる、またはコードを書く前からルールを教えたい | Agent Skills：/setup-svelte-vitals、/improve-svelte、/svelte-vitals |
比較
CLI （svelte-vitals） |
Vite プラグイン（ビルドモード） | Vite プラグイン（ライブダッシュボード） | |
|---|---|---|---|
| 読み取る対象 | ソース（.svelteファイル、レイアウトチェーン） |
プレレンダリング済みHTML出力 + .svelteソース（コンポーネントルール） |
起動時はソース、訪問済みルートはレンダリング済みHTML |
| カテゴリ | 全カテゴリ（SEO、Performance、Correctness、Security、Architecture、Accessibility） | 全カテゴリ（SEO、Performance、Correctness、Security、Architecture、Accessibility） | 全カテゴリ（静的ベースライン）、訪問済みルートはレンダリング済みSEO/Performance/Accessibilityの精度に精緻化 |
| 対象ルート | 全ルート（SSR、動的、プレレンダリング） | プレレンダリングされたルートのみ | 起動時から全ルート（訪問済みルートは measured に格上げ） |
| 実行タイミング | 任意（ターミナル、CI、pre-commit、エージェントのシェル） | vite build の都度 |
vite dev 実行中にライブ |
| ビルドが必要か | 不要 | 必要 | 不要 |
| 主な用途 | CI、pre-commitフック、単発の監査、エージェントのツールループ | ビルドパイプラインのゲート | ローカル開発中のフィードバック（デフォルトで有効） |
この表に意図的に載せていないものが2つあります。GitHub Action はCLI自身のエンジンをインプロセスで実行するため、カバー範囲はCLIの列そのものです。加わるのは別種の解析ではなく、PR上の体験（インラインアノテーション、ジョブサマリー、スティッキーコメント）です。Agent Skills は自前の解析を一切行わず、エージェントにルールの知識と、いつスキャナーを実行すべきかを教えるものです。
なぜビルドモードのカバー範囲はCLIに近いのか
Correctness、Security、Architecture、Accessibility のルールはコンポーネントのソースコード（$effectの中身、{@html}の呼び出し、propsの数、ARIA属性など）を読み取りますが、ソースコードはコンパイル前にしか存在しません。CLI、Vite プラグインのビルドモード、ライブダッシュボードの静的ベースラインの3つはいずれもソースを直接読み取るため、これらのルールを全カテゴリにわたって実行できます。
devで実際にルートを訪問すると、ダッシュボードはさらにそのルートのレンダリング済みHTMLを（svelteVitalsHandle 経由で）SEO/Performance/Accessibilityのルールで再チェックします。この再チェックはライブラリに依存せず、対象となるページについては正確です。何が <head> を生成したかに関わらず、配信されるHTMLにタグが欠けていれば検出します。静的ベースライン単体で得られないのは、この訪問済みルートに対するレンダリング済みHTMLの再チェックだけです。ビルドモードも同じ理由（正確な検証）でレンダリング済みHTMLを読み取りますが、それに加えてソーススキャンも行う唯一のビルド時経路です。
各パッケージの特徴
最も広いカバー範囲を持つ CLI
svelte-vitals はプロジェクトのソースを直接読むため、全ルート（SSR、動的ルートを含む）と全カテゴリをカバーできる唯一の直接的な経路です。ビルド不要で、Node が動く環境（ターミナル、CIジョブ、--staged によるpre-commitフック、--diff main によるPRチェックなど）ならどこでも実行できます。CIゲートを組むなら、まずここから始めてください。詳細は CLIリファレンス を参照してください。
ビルド成果物を正確に検証する Vite プラグイン
ビルドモードは vite build の実行中に、実際にプレレンダリングされた HTML を解析して SEO/Performance/Accessibility を検証します。何が生成したかに関わらず、タグが出力 HTML になければ検出され、failOn の閾値に達した時点でビルドが失敗します。加えて .svelte ソースも走査し、CLI と同じ Correctness・Security・Architecture と、コンポーネントスコープの Performance・Accessibility ルールを実行します。
トレードオフはルートの範囲です。HTML ベースの検証はプレレンダリングされたルートのみが対象で、コンポーネントスコープのルールはプロジェクト全体が対象です。詳細は プラグインモード を参照してください。
同じパッケージは vite dev 中に /__svelte-vitals/ でライブダッシュボードもデフォルトで配信しています。ビルドは不要で、起動時からプロジェクト全体をカバーし、ページを閲覧するにつれて実際のレンダリング結果へと精緻化されます。これはゲートではなくフィードバックであり、ビルドやCIを失敗させることはありません。詳細は ライブダッシュボード を参照してください。
YAMLを書かずにPRをゲートする GitHub Action
プルリクエストごとに CLI と同じエンジンを実行し、検出結果を GitHub ネイティブなフィードバック（インラインアノテーション、ジョブサマリー、その場で更新されるスティッキー PR コメント）に変換します。
npx svelte-vitals@latest ci install（または svelte-vitals install の ci-workflow ターゲット）が、SHA でピン留めした呼び出しを含むワークフローを生成します。ピンの更新は svelte-vitals ci upgrade。ワークフローは検出結果をその PR 自身の変更分に絞るため、既存の問題が他の人の PR を失敗させることはありません。詳細は CI 連携 を参照してください。
エージェントに前もってルールの知識を与える Agent Skills
Agent Skills は、エージェントが「コードを書く前からルールを知っている」状態を作ります。npx skills add oekazuma/svelte-vitals は Claude Code・Codex・Cursor で同じように動く SKILL.md をインストールします。
/setup-svelte-vitals は導入時のスキルで、プロジェクトが既に宣言している内容から svelte-vitals.config を導出し、各ルールを採用する前に必ず計測します。/improve-svelte は「アプリをレビューして」を影響度順の実装プランに変える読み取り専用の監査スキルです。/svelte-vitals はルールカタログと「編集のたびに実行する」プレイブックを埋め込みます。
CLI を置き換えるのではなく補完します。知識は前もって、解析は必要なときに。プレイブック自身が、編集後には npx svelte-vitals . --diff --reporter agent を、ルールの根拠やオプションには npx svelte-vitals explain <rule-id> を実行するよう指示します。
おすすめの組み合わせ
- まず始めるなら: ローカルで
npx svelte-vitals@latestを実行し、CIにも追加します（npx svelte-vitals@latest --fail-on critical）。これだけで全カテゴリ、全ルートをカバーできます。 - GitHubでホスティングしているなら: そのCIステップを手書きする代わりに
npx svelte-vitals@latest ci installを使います。エンジンは同じまま、インラインPRアノテーションとスティッキーコメントが加わり、対象は各PR自身の変更分に絞られます。 - AI エージェントと一緒にコーディングするなら: Agent Skills をセットアップします（
npx skills add oekazuma/svelte-vitals）。スキルはコードを書く前のエージェントにルールを与え、書いた後は CLI（--diff --reporter agent）で検証させます。 - プレレンダリング/マーケティングページを磨き込むなら: Vite プラグインのビルドモードで、配信HTMLをビルド時に正確にゲートします。ライブダッシュボードはデフォルトで有効なので、執筆中のライブフィードバックも追加のセットアップなしで得られます。
- これらすべてを組み合わせるのが一般的な最終形です。それぞれ異なるタイミングで異なる対象をチェックするため、競合しません。