Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/vite-component-rules-cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'svelte-vitals': patch
---

Internal refactor: component-facts source parsing (`parseComponentFacts` and its shared AST utilities) moved to `@svelte-vitals/core` so `@svelte-vitals/vite` can reuse it. No user-facing behavior change.
5 changes: 5 additions & 0 deletions .changeset/vite-component-rules-core.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@svelte-vitals/core': minor
---

Export `parseComponentFacts` (and the Svelte-AST utilities it's built on — `attrValue`, `attrValueOf`, `attrTextOf`, `findAttr`, `lineOf`, `CHILD_NODE_KEYS`, `valueFromNodes`, `textFromNodes`, `attrText`) from the package root. This is the same `.svelte`-source parser the CLI has always used for Correctness/Security/Architecture/Bundle-Performance rules, relocated from `svelte-vitals` so `@svelte-vitals/vite` can use it too. `@svelte-vitals/core` gains a new `svelte` dependency (for `svelte/compiler`'s `parse`) — a pure parsing call, so this doesn't affect the package's runtime-agnostic status.
5 changes: 5 additions & 0 deletions .changeset/vite-component-rules-vite.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@svelte-vitals/vite': minor
---

Build mode now additionally scans `.svelte` source under `src/` and runs Correctness, Security, Architecture, and the two component-scoped Performance rules (PERF009/PERF010) — the same rules the CLI and MCP already run — enabled by default alongside the existing rendered-HTML SEO/Performance checks. The dev overlay is unchanged (still SEO/Performance-only, rendered-HTML-based). Use the existing `rules` option to opt individual rules out, e.g. `{ CORRECT002: 'off' }`.
24 changes: 12 additions & 12 deletions docs/src/content/docs/guides/choosing-a-package.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,20 +19,20 @@ svelte-vitals ships as three packages — `svelte-vitals` (CLI), `@svelte-vitals

## Comparison

| | CLI (`svelte-vitals`) | Vite plugin — build mode | Vite plugin — dev overlay | MCP server |
| -------------- | ------------------------------------------------------------- | ------------------------ | --------------------------------- | -------------------------------- |
| Reads | Source (`.svelte` files, layout chain) | Prerendered HTML output | Rendered HTML, per dev request | Source (same engine as the CLI) |
| Categories | All 5 — SEO, Performance, Correctness, Security, Architecture | SEO, Performance | SEO, Performance | All 5 |
| Routes covered | Every route — SSR, dynamic, prerendered | Prerendered routes only | Only routes you've visited in dev | Every route |
| Runs | On demand — terminal, CI, pre-commit | Every `vite build` | Live, while `vite dev` runs | On demand — an agent's tool call |
| Needs a build | No | Yes | No | No |
| Typical home | CI, pre-commit hooks, one-off audits | Build pipeline gate | Local dev feedback | An AI agent's tool loop |
| | CLI (`svelte-vitals`) | Vite plugin — build mode | Vite plugin — dev overlay | MCP server |
| -------------- | ------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------- | -------------------------------- |
| Reads | Source (`.svelte` files, layout chain) | Prerendered HTML output + `.svelte` source (component rules) | Rendered HTML, per dev request | Source (same engine as the CLI) |
| Categories | All 5 — SEO, Performance, Correctness, Security, Architecture | All 5 — SEO, Performance, Correctness, Security, Architecture | SEO, Performance | All 5 |
| Routes covered | Every route — SSR, dynamic, prerendered | Prerendered routes only | Only routes you've visited in dev | Every route |
| Runs | On demand — terminal, CI, pre-commit | Every `vite build` | Live, while `vite dev` runs | On demand — an agent's tool call |
| Needs a build | No | Yes | No | No |
| Typical home | CI, pre-commit hooks, one-off audits | Build pipeline gate | Local dev feedback | An AI agent's tool loop |

### Why the coverage differs
### Why build-mode coverage is close to the CLI's

Correctness, Security, and Architecture rules read component **source** — `$effect` bodies, `{@html}` calls, prop counts — which only exists before compilation. Only the two paths that read source directly (the CLI and MCP, which runs the CLI's own analysis engine) can run them.
Correctness, Security, and Architecture rules read component **source** — `$effect` bodies, `{@html}` calls, prop counts — which only exists before compilation. The CLI, MCP (which runs the CLI's own analysis engine), and the Vite plugin's **build mode** all read this source directly, so all three run the full 5-category rule set.

The Vite plugin, in both its build and dev-overlay forms, inspects **HTML** instead — the prerendered output or the rendered response. That makes it SEO/Performance-only, but also library-agnostic and exact for the pages it covers: whatever produced the `<head>`, if it's missing from the shipped HTML, the plugin sees it. It's the only path that inspects what a browser actually receives.
The dev overlay is the one path that inspects **rendered HTML only** (the response for each route you visit, with no whole-project source scan), which keeps it SEO/Performance-only, but library-agnostic and exact for the pages it covers: whatever produced the `<head>`, if it's missing from the shipped HTML, the overlay sees it. Build mode reads rendered HTML too (for the same exact-verification reason), _in addition to_ the source scan — it's the only path that gets both.

## The packages

Expand All @@ -42,7 +42,7 @@ The Vite plugin, in both its build and dev-overlay forms, inspects **HTML** inst

### Vite plugin — exact, build-time verification

`@svelte-vitals/vite`'s build mode runs during `vite build` and parses the **actual prerendered HTML**, so it can't be fooled by a component the source scanner doesn't recognize — if the tag isn't in the shipped output, it fails. The trade-off is scope: only prerendered routes, and only the head/DOM-based SEO and Performance rules. See [Plugin mode](/svelte-vitals/guides/plugin-mode/).
`@svelte-vitals/vite`'s build mode runs during `vite build` and parses the **actual prerendered HTML** for SEO/Performance, so it can't be fooled by a component the source scanner doesn't recognize — if the tag isn't in the shipped output, it fails. It also scans `.svelte` source directly for Correctness, Security, Architecture, and the two component-scoped Performance rules, the same as the CLI. The remaining trade-off is route scope: only prerendered routes get the HTML-based SEO/Performance verification (component-scoped rules apply project-wide). See [Plugin mode](/svelte-vitals/guides/plugin-mode/).

The same package also adds a **dev overlay** — live warnings in the terminal (and an optional dashboard at `/__svelte-vitals/`) as you navigate `vite dev`, with zero build step. It's feedback, not a gate: nothing here fails a build or a CI run. See [Dev overlay](/svelte-vitals/guides/dev-overlay/).

Expand Down
2 changes: 2 additions & 0 deletions docs/src/content/docs/guides/dev-overlay.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,3 +81,5 @@ It is fed by the dev handle (the same one the overlay above uses), so keep `svel
Live updates only flow over a loopback origin (`localhost`, `127.0.0.1`, `[::1]`). When you run `vite dev --host` and open the app via a LAN IP, the handle skips the ingest POST (a guard against a spoofed `Host` header), so the dashboard stays empty — open it from `localhost` instead. Set `SVELTE_VITALS_DEBUG=true` to log when an ingest is skipped.

Like the overlay, this is dev-only and rendered-based: it covers the SEO `<head>` rules for the routes you visit. For a whole-project report (all routes, Performance, site checks), run `npx svelte-vitals` or `npx svelte-vitals --reporter html`.

Component-scoped rules (Correctness, Security, Architecture, and the two component-scoped Performance rules) are build-mode-only — see [Plugin mode](/svelte-vitals/guides/plugin-mode/) — and never appear in the dev overlay, since there is no whole-project source scan on a per-request rendered view.
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/plugin-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar:
order: 4
---

`@svelte-vitals/vite` is a Vite / SvelteKit plugin that piggybacks on `vite build`, parses the **prerendered HTML's `<head>`**, and runs the same SEO and Performance rules as the CLI. Because it inspects the real HTML output, it is library-agnostic. The build fails when findings reach the `failOn` threshold.
`@svelte-vitals/vite` is a Vite / SvelteKit plugin that piggybacks on `vite build`, parses the **prerendered HTML's `<head>`**, and runs the same SEO and Performance rules as the CLI. Because it inspects the real HTML output, it is library-agnostic. Build mode additionally scans your `.svelte` source directly under `src/` for Correctness, Security, Architecture, and the two component-scoped Performance rules (PERF009/PERF010 — heavy/namespace imports) — the same component-scoped rules the CLI runs, enabled by default. The build fails when findings reach the `failOn` threshold.

> **ESM-only** (Node 18+). Ships ES modules only; `require()` is unsupported by design.

Expand Down
24 changes: 12 additions & 12 deletions docs/src/content/docs/ja/guides/choosing-a-package.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,20 +19,20 @@ svelte-vitals は `svelte-vitals`(CLI)、`@svelte-vitals/vite`(プラグイン +

## 比較

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

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

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

一方Vite プラグインは、ビルドモード・開発オーバーレイのどちらも**HTML**を検査します(プレレンダリングされた出力、またはレンダリング済みのレスポンス)。そのためSEO/Performanceのみに限定されますが、カバーする範囲においてはライブラリ非依存かつ正確です — 何が `<head>` を生成したかに関わらず、実際に配信されるHTMLに欠けていればそれを検出します。ブラウザが実際に受け取るものを検査できるのはこの経路だけです。
開発オーバーレイだけが**レンダリング済みHTMLのみ**を検査する経路です(訪問した各ルートのレスポンスのみ、プロジェクト全体を横断するソーススキャンはありません)。そのためSEO/Performanceのみに限定されますが、カバーする範囲においてはライブラリ非依存かつ正確です — 何が `<head>` を生成したかに関わらず、実際に配信されるHTMLに欠けていればそれを検出します。ビルドモードも同じ理由でレンダリング済みHTMLを読み取りますが、それに**加えて**ソーススキャンも行う唯一の経路です。

## 各パッケージの特徴

Expand All @@ -42,7 +42,7 @@ Correctness・Security・Architecture のルールはコンポーネントの**

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

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

同じパッケージには**開発オーバーレイ**も含まれており、`vite dev` を実行してページを巡回するだけで、ビルド不要でターミナルにライブ警告(任意でダッシュボードを `/__svelte-vitals/` に)を表示します。これはゲートではなくフィードバックです — ビルドやCIを失敗させることはありません。詳細は [開発オーバーレイ](/svelte-vitals/ja/guides/dev-overlay/) を参照してください。

Expand Down
2 changes: 2 additions & 0 deletions docs/src/content/docs/ja/guides/dev-overlay.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,3 +81,5 @@ export default {
ライブ更新はループバックオリジン(`localhost`・`127.0.0.1`・`[::1]`)でのみ流れます。`vite dev --host` で LAN の IP からアプリを開いた場合、ハンドルは ingest の POST をスキップする(`Host` ヘッダー偽装への防御)ため、ダッシュボードは空のままになります。その場合は `localhost` から開いてください。`SVELTE_VITALS_DEBUG=true` を設定すると、ingest がスキップされた際にログが出力されます。

オーバーレイと同様、これは dev 専用かつレンダリングベースで、訪問したルートの SEO `<head>` ルールを対象とします。プロジェクト全体のレポート(全ルート・パフォーマンス・サイト全体のチェック)が必要な場合は `npx svelte-vitals` または `npx svelte-vitals --reporter html` を実行してください。

コンポーネントスコープのルール(Correctness・Security・Architecture、および2つのコンポーネントスコープの Performance ルール)はビルドモードのみの対応です([プラグインモード](/svelte-vitals/ja/guides/plugin-mode/) を参照) — リクエスト単位のレンダリング済みビューにはプロジェクト全体を横断するソーススキャンが存在しないため、開発オーバーレイには表示されません。
Loading