Choosing a package

Which svelte-vitals package to use, and when to combine them. CLI, Vite plugin, GitHub Action, or Agent Skills.

There are two npm packages: svelte-vitals, the CLI, and @svelte-vitals/vite, the plugin plus live dashboard. Two more pieces don’t come from npm. @svelte-vitals/action is consumed straight from its repo, and Agent Skills are SKILL.md files installed from skills.sh with npx skills add.

The CLI, the plugin and the Action share one rule engine and scoring but read different input. Agent Skills analyze nothing themselves. They carry the rule knowledge and tell the agent when to run the scanner. Most projects use more than one.

Each package is versioned independently and depends on @svelte-vitals/core (the shared rule engine) as its own semver range, so two packages installed at the “same time” can still resolve to different core versions. If the CLI and the Vite plugin ever disagree on findings for the same project, see live dashboard: Version drift.

Quick answer

Comparison

Two pieces are deliberately absent from this table. The GitHub Action runs the CLI’s own engine in-process, so its coverage is the CLI column; what it adds is the PR experience rather than different analysis, meaning inline annotations, a job summary and a sticky comment. Agent Skills run no analysis of their own at all. They give the agent the rule knowledge and tell it when to run the scanner.

Why build-mode coverage is close to the CLI’s

Correctness, Security, Architecture, and Accessibility rules read component source: $effect bodies, {@html} calls, prop counts, ARIA attributes. That source only exists before compilation. The CLI, the Vite plugin’s build mode, and the live dashboard’s whole-project static baseline all read it directly, so all three run those rules across every category.

Visiting a route in dev additionally re-checks its rendered HTML through svelteVitalsHandle, for SEO, Performance and Accessibility. That is the one thing the static baseline alone can’t give you. Build mode reads rendered HTML too, on top of the source scan, making it the only build-time path with both.

The packages

CLI: broadest coverage

svelte-vitals reads your project’s source directly, so it’s the only direct path that covers every route (including SSR and dynamic ones) and all categories. It needs no build and runs anywhere Node does: a terminal, a CI job, a pre-commit hook via --staged, or a PR check via --diff main. Start here for CI gating; see the CLI reference.

Vite plugin: exact, build-time verification

Build mode runs during vite build and parses the actual prerendered HTML for SEO, Performance and Accessibility. If the tag isn’t in the shipped output, svelte-vitals reports it, whatever produced it, and the build fails once a finding reaches the failOn threshold. It also scans .svelte source for Correctness, Security, Architecture and the component-scoped Performance and Accessibility rules, as the CLI does.

The trade-off is route scope. Only prerendered routes get the HTML check; component-scoped rules apply project-wide. See Plugin mode.

The same package also serves a live dashboard at /__svelte-vitals/ during vite dev, on by default, with no build step. It gives you whole-project coverage from startup, refined to real rendered results as you browse. It’s feedback, not a gate: nothing here fails a build or a CI run. See Live dashboard.

GitHub Action: PR gating with zero YAML

Runs the CLI’s engine on every pull request and turns findings into GitHub-native feedback: inline annotations, a job summary, and one sticky PR comment that updates in place.

npx svelte-vitals@latest ci install (or the ci-workflow install target) scaffolds a workflow calling it pinned to a SHA; svelte-vitals ci upgrade bumps that pin. The workflow scopes findings to the PR’s own changes, so pre-existing issues don’t fail other people’s PRs. See CI integration.

Agent Skills: rule knowledge for your agent, up front

Agent Skills make an agent know the rules before it writes code. npx skills add oekazuma/svelte-vitals installs portable SKILL.md files that work identically in Claude Code, Codex and Cursor.

/setup-svelte-vitals is the adoption pass. It derives a svelte-vitals.config from what the project already declares, measuring each rule before adopting it. /improve-svelte is a read-only audit that turns “review my app” into impact-ranked implementation plans. /svelte-vitals embeds the rule catalog plus a run-after-every-edit playbook.

They pair with the CLI rather than replace it: knowledge up front, analysis on demand. The playbook itself tells the agent to run npx svelte-vitals . --diff --reporter agent after an edit, and npx svelte-vitals explain <rule-id> for a rule’s rationale and options.

Recommended setups

• Just starting out. Run npx svelte-vitals@latest locally, then add it to CI with npx svelte-vitals@latest --fail-on critical. This alone covers all categories and every route.
• Hosting on GitHub. Run npx svelte-vitals@latest ci install instead of hand-writing that CI step. Same engine, plus inline PR annotations and the sticky comment, scoped to each PR’s own changes.
• Coding with an AI agent. Install the Agent Skills with npx skills add oekazuma/svelte-vitals. They give the agent the rules before it writes code, and tell it to verify each edit afterward with the CLI’s --diff --reporter agent.
• Polishing prerendered or marketing pages. Add the Vite plugin’s build mode for an exact, build-time gate on shipped HTML. Its live dashboard, on by default, gives you feedback while you write, with no extra setup.
• All of the above together is the common end state. They check different things at different times and don’t conflict.