svelte-vitals install

Set up the Vite integration, Cursor rules, the config file, and CI.

Interactively set up the svelte-vitals Vite integration, Cursor rules, the config file, and the CI workflow. Everything a project needs, wired up in one pass. Agent Skills are installed separately, with npx skills add oekazuma/svelte-vitals.

npx svelte-vitals@latest install

With no flags it launches an interactive wizard: pick your targets, review the plan, and confirm. The picker groups targets by category, so it’s clear what each one is for: Vite integration, Agent rules, CI (GitHub Actions), Config file. For non-interactive and CI use, drive it entirely with flags.

Every flag svelte-vitals install --help prints, generated from the CLI’s own argument declarations. The sections after the table give the full behavior per target.

--client <ids>

Comma-separated targets to configure: vite-plugin, vite-hooks, cursor-rules, config-file, ci-workflow. When given, the interactive picker is skipped.

vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs} (the live dashboard is on by default); vite-hooks wires svelteVitalsHandle into src/hooks.server.{ts,js}, improving the dashboard’s per-route accuracy as you browse.

Both use a magicast codemod that only touches a file whose shape it confidently recognizes. Anything else it leaves alone, printing a snippet instead. Writing either installs @svelte-vitals/vite via the detected package manager if it isn’t already a dependency. --force does not apply to these two: an existing registration is always left as-is.

cursor-rules writes .cursor/rules/svelte-vitals.mdc, generated at install time from the current rule set (id, title, severity and rationale per rule, grouped by category). Because it is regenerated rather than codemodded, --force does apply and overwrites it. (The /setup-svelte-vitals, /improve-svelte and /svelte-vitals Agent Skills are not installer targets; install them with npx skills add oekazuma/svelte-vitals.)

config-file scaffolds svelte-vitals.config.{js,ts} with every option (treatDynamicAs, metaComponents, rules, failOn, weights) commented out, auto-picking the best extension for the environment; see Config file. Like cursor-rules, it’s fully regenerated, so --force does apply, to whichever file already exists. Regenerating never switches that file’s extension.

ci-workflow scaffolds .github/workflows/svelte-vitals.yml, the same file the standalone svelte-vitals ci install command writes. Pick it here to set up CI in the same pass as everything else, instead of a separate command. It’s fully regenerated, so --force does apply; svelte-vitals ci upgrade (not part of this wizard) remains the way to bump an existing workflow’s pinned action version without touching anything else in the file.

--app <app> in monorepos

The vite-plugin, vite-hooks, and config-file targets must land in the SvelteKit app directory. That’s where vite.config.* and src/hooks.server.* live, and svelte-vitals only loads a svelte-vitals.config.* from the analyzed directory. When you run install from a monorepo root, these targets resolve their app the same way the analyzer does:

• An explicit --app apps/web always wins, and fails with exit 2 when that directory is not a SvelteKit app, meaning it has neither a svelte.config.{js,ts} nor a package.json declaring @sveltejs/kit.
• Otherwise, if the current directory is itself a SvelteKit app, it’s used as-is.
• Otherwise detection takes over: exactly one app found → used automatically with a notice; several found → a picker prompt on an interactive terminal, or exit 2 asking for --app when non-interactive.

Everything else, cursor-rules and ci-workflow, always writes relative to the current directory, since the repo root is those files’ correct home in a monorepo.

cd my-monorepo
npx svelte-vitals@latest install --client vite-plugin,config-file --app apps/web --yes

--yes, -y

Skip the confirmation prompt.

--dry-run

Print the planned changes and exit without writing anything.

--force

Overwrite an existing svelte-vitals entry. By default an entry that already exists is left untouched.

--refresh

Regenerates a cursor-rules file already on disk with the current rule set, which is how you pick up new rules after an upgrade. It never creates a file that isn’t there. (Agent Skills installed with npx skills add are updated by the skills CLI, not by --refresh.)

--yes, --force and --app are ignored with a warning; --client is a fatal combination. With no generated files present it prints guidance and exits 0.

# Non-interactive: write the Cursor rules file and register the Vite plugin
npx svelte-vitals@latest install --client cursor-rules,vite-plugin --yes

# Preview what would change, without writing
npx svelte-vitals@latest install --client config-file --dry-run

# Regenerate an already-installed Cursor rules file after adding a rule
npx svelte-vitals@latest install --refresh

# Set up CI in the same pass as everything else
npx svelte-vitals@latest install --client cursor-rules,ci-workflow --yes

If a target file can’t be read, the command reports the path and exits 2 rather than writing over something it could not inspect.

An unrecognized --client id warns and is skipped; the remaining valid targets still install. If none of the ids are valid, the command fails instead of installing nothing silently.