プラグインモード
ビルド時にプリレンダリングされた HTML を分析するために svelte-vitals を vite build に統合します。
@svelte-vitals/vite は vite build に相乗りしてプリレンダリングされた HTML を解析し、CLI と同じ SEO・Performance・Accessibility のルールを実行します（src/app.html を読む a11y/doctype だけは CLI 専用です）。実際の出力を検査するので、使っているライブラリを問いません。
さらに src/ 配下（コンポーネント、runes モジュール（.svelte.ts/.svelte.js）、ルート/フックファイル）を走査し、Correctness・Security・Architecture・残りの Accessibility とコンポーネントスコープの Performance ルールも実行します。デフォルトで有効です。検出結果が failOn の閾値に達するとビルドが失敗します。
ESM のみ（Node 24.16+）。ES モジュールのみを提供します。
require()は設計上サポートされていません。
インストール
npm install --save-dev @svelte-vitals/vite svelte-vitals
# または
pnpm add -D @svelte-vitals/vite svelte-vitalssvelte-vitals と @svelte-vitals/core はプラグインの peer dependency です。両パッケージがプロジェクトのインストールからルールエンジンを解決するため、バージョン不一致は「スキャンは通るのに vite build が落ちる」ではなく、インストール時の peer 警告として現れます。npm と pnpm は不足している peer を自動インストールしますが、svelte-vitals を明示的に宣言しておくとバージョンが lockfile の管理下に置かれます。peer を自動インストールしない yarn では、明示的な宣言が必須です（Plug’n’Play では @svelte-vitals/core も追加してください。classic yarn は推移的に解決します）。
セットアップ
vite.config.ts に svelteVitals を追加します。
import { sveltekit } from '@sveltejs/kit/vite';
import { svelteVitals } from '@svelte-vitals/vite';
export default {
plugins: [sveltekit(), svelteVitals({ failOn: 'critical', report: 'console' })]
};オプション
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
failOn |
'critical' | 'warning' | 'info' |
'critical' |
ビルドを失敗させる最低重大度 |
report |
'console' | 'json' | false |
'console' |
分析レポートの出力形式 |
outFile |
string |
— | JSON レポートをこのパスのファイルに書き込む |
rules |
Record<string, 'off' | 'critical' | 'warning' | 'info'> |
{} |
ルールごとの上書き（ルールを無効化するか重大度を変更する） |
metaComponents |
string[] |
— | 解析が追跡できないヘッドメタデータ出力コンポーネント名（解決できるリポジトリ内のコンポーネントは自動的に追跡される） |
treatDynamicAs |
'pass' | 'warn' | 'fail' |
'pass' |
動的に設定されたメタデータの扱い方 |
weights |
Partial<Record<Category, number>> |
各カテゴリ 1 |
レポート内の組み合わせた Health スコアのカテゴリごとの重み |
prerenderDir |
string |
— | プリレンダリングページディレクトリの上書き |
ui |
boolean |
true |
vite dev 中にライブダッシュボードを配信するかどうか。false にするとビルド時ゲートのみになる |
cwd |
string |
Vite のルート | プロジェクトルート |
設定ファイル
@svelte-vitals/vite はプロジェクトルートの svelte-vitals.config.* を自動的に読み込みます。上記の明示的なオプションは常に設定ファイルの値より優先されます。優先順位のルールと、ライブダッシュボードが設定ファイルをどう利用するかは 設定ファイル § Vite プラグインで設定ファイルを再利用する を参照してください。
同じ場所にある svelte-vitals-suppressions.json（svelte-vitals --update-suppressions が書き出すファイル）も、ビルドゲートとライブダッシュボードのプロジェクト全体レイヤーの両方に適用され、CLI と結果が一致します。適用されるのはソース走査のエントリだけです（Correctness、Security、Architecture、コンポーネント単位の Accessibility。ルール ID・route・location が CLI と共通の検出結果）。レンダリング後のルート検出結果はビルド済み HTML ファイルに紐づき、CLI が記録する +page.svelte とは location が異なるため、プラグインはルート単位のエントリをビルドゲート・ダッシュボードのどちらでもスキップし、スキップした件数を出力します。それらには overrides を使ってください。ビルド時には抑制した件数も出力します。stale なエントリの報告は CLI だけが行います。壊れたファイルは CLI と同様にビルドを失敗させます。
対象範囲
HTML の検査対象はプリレンダリングされたルートのみです。プリレンダリングされないルート（サーバーレンダリングのルートや、プリレンダリング対象のエントリを持たない動的ルート）にはビルド出力がないので、ここではレンダリング後の HTML を読めません。ssr = false のプリレンダリングされたルートにはビルド出力がありますが、中身は空のアプリシェルなので HTML 検査はこれもスキップします（ssr = false の +layout はそのサブツリー全体を、kit.router.type: 'hash' はすべてのルートをスキップ）。スキップしたルートはビルド時に警告 1 行で列挙します。プリレンダリング中にリダイレクトしたルートは、ページではなく SvelteKit のリダイレクト用スタブとして出力されるので、HTML 検査は警告なしでスキップします。ビルド時にたまたま発動した条件付きリダイレクトもここに含まれますが、CLI はこれもソースから検査します。これらのルートは svelte-vitals CLI がソース解析でカバーし、vite dev 中にブラウズすればライブダッシュボードがレンダリング結果を読み取ります。ソース走査のほうは、ルートのレンダリング方式に関係なくプロジェクト全体が対象です。ビルドが 1 ページもプリレンダリングしなかった場合（フォールバックページで配信する SPA など）は、ルート解析をスキップした旨の警告を 1 行出したうえで、ソース走査は実行してビルドの判定にも使います。レンダリング後の <html> を読む seo/html-lang はこのときスキップします。
Vitest 実行中、このプラグインは何もしません。Vitest は同じ Vite 設定を読み込んでテスト用の開発サーバーを起動するため、そのままではダッシュボードの解析が走り、テスト出力の途中に通知が混ざります。そこでは何も実行しません。vite dev と vite build の動作は変わりません。
動作の仕組み
vite build 中、SvelteKit がページをプリレンダリングした後、@svelte-vitals/vite は出力された HTML ファイルを探して各ページの <head> と本文を解析し、あわせて src/ を走査してソースレベルのルールを実行します。読んでいるのは実際に配信される HTML なので、動的な値もすでに解決済みです。CLI では ↯ dynamic としか判定できない <title> も、ここでは実際の中身に対して検査されます。いずれかの検出結果が failOn の閾値に達すると、ビルドプロセスは非ゼロの終了コードで終わります。
ライブダッシュボード
開発時には、@svelte-vitals/vite は /__svelte-vitals/ でライブダッシュボードも配信します（デフォルトで有効）。詳細は ライブダッシュボード を参照してください。