プラグインモード

ビルド時にプリレンダリングされた 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-vitals

svelte-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 プラグインで設定ファイルを再利用するを参照してください。

対象範囲

HTML の検査対象はプリレンダリングされたルートのみです。SSR や動的ルートにはビルド出力がないので、ここではレンダリング後の HTML を読めません。これらのルートは svelte-vitals CLI がソース解析でカバーし、vite dev 中にブラウズすればライブダッシュボードがレンダリング結果を読み取ります。ソース走査のほうは、ルートのレンダリング方式に関係なくプロジェクト全体が対象です。

動作の仕組み

vite build 中、SvelteKit がページをプリレンダリングした後、@svelte-vitals/vite は出力された HTML ファイルを探して各ページの <head> と本文を解析し、あわせて src/ を走査してソースレベルのルールを実行します。読んでいるのは実際に配信される HTML なので、動的な値もすでに解決済みです。CLI では ↯ dynamic としか判定できない <title> も、ここでは実際の中身に対して検査されます。いずれかの検出結果が failOn の閾値に達すると、ビルドプロセスは非ゼロの終了コードで終わります。

ライブダッシュボード

開発時には、@svelte-vitals/vite は /__svelte-vitals/ でライブダッシュボードも配信します（デフォルトで有効）。詳細はライブダッシュボードを参照してください。