svelte-vitals

Your SvelteKit app's code health, checked before it ships. Statically, no browser. Scores SEO, Performance, Correctness, Security, Architecture, and Accessibility by reading your source code.

ESM-only (Node 24.16+). Ships ES modules only; require() is unsupported by design.

npx svelte-vitals@latest

[!WARNING] Pre-1.0. APIs, rule IDs, scoring, and output formats can change at any time, including breaking changes between minor releases.

Usage

Run inside any SvelteKit project:

npx svelte-vitals@latest              # analyze the current directory
npx svelte-vitals@latest ./apps/web   # or a specific path

Svelte Vitals  ·  static mode

Health: 76/100
SEO Score: 51/100   (route avg 61 · site −10)
Architecture Score: 100/100   (route avg 100)

Critical (1)
────────────────────────
✗ seo/title-presence  Missing <title>
            /
            src/routes/+page.svelte

Warnings (10)
────────────────────────
✗ seo/canonical-url  Missing <link rel="canonical">
            /
            src/routes/+page.svelte
            …and 1 more
…and 1 more rule affected — run with --verbose to see all

Passed (11)
────────────────────────

↯ = set dynamically (verified at runtime).

By default, console output groups failures by rule (top 5 per severity, each with one example location and an "…and N more" count) and collapses the Passed section to a bare count, so large projects don't flood the terminal. Pass --verbose to see every finding uncapped and ungrouped, with each passed item listed individually. On an interactive, color-capable terminal the Health score plays a short reveal animation; pass --no-animation to disable it.

On an interactive terminal wide enough for the mascot (20+ columns), a small line-art face appears alongside both the analysis spinner and the Health-score reveal, reacting to the score (a perfect 100 gets a confetti flourish). On a wider terminal still (55+ columns) it also greets you with a short line in a speech bubble at startup, and again with a matching reaction line at the score reveal. --no-animation disables all of it, falling back to the plain spinner and plain score animation.

Exit codes

| Code | Meaning | | ---- | --------------------------------------------------------------------------- | | 0 | No failing findings | | 1 | Critical finding present, or --fail-on / --min-health threshold reached | | 2 | Execution error (not a SvelteKit project, internal error, etc.) |

Useful as a CI gate.

Reporters

--reporter <fmt> selects the output format: console (default), json, agent, sarif, github, html (self-contained, --out-file), and md (compact, for PR comments/job summaries). agent auto-selects inside known AI-agent harnesses (e.g. Claude Code); github auto-selects under GitHub Actions.

Ramping up on an existing project

--diff [ref] / --staged scope findings to changed/staged files; --baseline <ref> scopes to findings that are genuinely new versus a ref; --update-suppressions records today's findings once so only newly-introduced issues gate the build afterward. --rules/--ignore/--category select which rules run, --weights reweights the combined Health score, and --min-health/--score gate or print just the number. A svelte-vitals.config.{js,ts} file (scaffolded via svelte-vitals install --client config-file) can set any of these once instead of repeating flags.

svelte-vitals install

An interactive wizard that wires up the Vite plugin's live dashboard, a Cursor rules file, a svelte-vitals.config file, and a GitHub Actions CI workflow, grouped by category in the picker so it's clear what each target is for:

npx svelte-vitals@latest install

The /setup-svelte-vitals, /improve-svelte and /svelte-vitals Agent Skills are not installer targets. Install them with npx skills add oekazuma/svelte-vitals.

svelte-vitals docs / svelte-vitals explain

Both read out of the CLI itself, so the answer always matches the installed version and needs no network, which is the thing an AI agent otherwise guesses at or fetches from a page describing a different release.

npx svelte-vitals@latest docs list             # every bundled topic, with a one-line description
npx svelte-vitals@latest docs show scoping
npx svelte-vitals@latest explain --list        # every rule, by category
npx svelte-vitals@latest explain performance/heavy-import

explain <rule-id> prints that rule's rationale, docs link, fix template, and, for a configurable rule, every option's default, bounds, and how a configured value merges with the built-in default: the detail needed to decide whether a finding is a defect or a threshold disagreement. docs list and both forms of explain take --json; docs show prints the topic as Markdown.

CI integration

svelte-vitals ci install scaffolds a GitHub Actions workflow around @svelte-vitals/action: inline PR annotations, a job summary, and a sticky PR comment, with no YAML to hand-write. The same workflow is also a selectable ci-workflow target inside svelte-vitals install, so it can be set up in the same pass as everything else. See CI integration.

Agent-native output

svelte-vitals --reporter agent emits a Markdown remediation document an AI coding agent can act on directly: each failing finding lists its location, a concrete fix (with a code snippet), and an acceptance check.

It is selected automatically when run inside a known AI-agent harness (e.g. Claude Code sets CLAUDECODE). Force it anywhere with SVELTE_VITALS_REPORTER=agent, or override with --reporter console|json. When auto-selected (not requested explicitly), a one-line hint is printed to stderr explaining how to override, so a human running it in an agent terminal isn't surprised by the Markdown output.

How it works

svelte-vitals resolves the effective <head> of every route by walking the layout chain (+layout.svelte → … → +page.svelte) and parsing <svelte:head> with svelte/compiler.

A dynamic title such as <title>{data.title}</title>, the most common and correct SvelteKit pattern, is never flagged as missing; it passes with a ↯ marker. Only genuinely missing or empty metadata is penalized.

See the full documentation for every flag, rule, and reporter, or the project README for the full picture and roadmap.

License

MIT © Kazuma Oe