--- title: svelte-vitals install description: Set up the Vite integration, Cursor rules, the config file, and CI. sidebar: order: 2 --- Interactively set up the svelte-vitals Vite integration, Cursor rules, the [config file](/guides/configuration), and the [CI workflow](/guides/ci). Everything a project needs, wired up in one pass. [Agent Skills](/guides/agent-skills) are installed separately, with `npx skills add oekazuma/svelte-vitals`. ```bash 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. | Flag | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--client ` | Comma-separated: vite-plugin,vite-hooks,cursor-rules,config-file,ci-workflow (skips the interactive picker; the picker groups these by category — Vite integration, Agent rules, CI, Config file) vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs}; vite-hooks wires up the svelteVitalsHandle hook in src/hooks.server.{ts,js}, which improves the live dashboard's per-route accuracy as you browse. --force does not apply to either of these two — an existing registration is always left as-is. cursor-rules writes a Cursor rules file (.cursor/rules/svelte-vitals.mdc), generated from the current rule set; supports --force to regenerate. The setup-svelte-vitals, improve-svelte and svelte-vitals Agent Skills are not installed here — install them with `npx skills add oekazuma/svelte-vitals`. config-file scaffolds svelte-vitals.config.{js,ts} with every option commented out, auto-picking .ts (with defineConfig) when the project looks TypeScript-oriented (tsconfig.json or vite.config.ts present) and svelte-vitals is a declared dependency (defineConfig's import resolves at load time); else the .js (ESM) default. Supports --force to regenerate the file that's already there (its extension never changes on --force). ci-workflow scaffolds .github/workflows/svelte-vitals.yml, the same file `svelte-vitals ci install` writes standalone — pick it here to set it up in the same pass as everything else; supports --force to regenerate. `svelte-vitals ci upgrade` remains the way to bump an existing workflow's pinned action version. | | `--app ` | Monorepo: the SvelteKit app directory the vite-plugin/vite-hooks/config-file targets write into (e.g. --app apps/web). Without it, when the current directory isn't itself a SvelteKit app, one detected app is used automatically (with a notice), several prompt a picker on a TTY, and non-interactive runs exit 2 asking for --app. All other targets (cursor-rules, ci-workflow) always write at the current directory — the repo root is their correct home. | | `-y, --yes` | Skip the confirmation prompt | | `--dry-run` | Print the planned changes and exit without writing | | `--force` | Overwrite an existing svelte-vitals entry | | `--refresh` | Regenerate an existing Cursor rules file (cursor-rules) with the current rule set. Only regenerates a file already present on disk — it never creates one. Cannot be combined with --client. | | `-h, --help` | Show this help | ## `--client ` 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](/guides/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](/guides/configuration). 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`](/guides/ci) 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 ` 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](/guides/configuration#where-it-lives). When you run `install` from a monorepo root, these targets resolve their app the same way [the analyzer does](/guides/cli#monorepos): - 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. ```bash 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`. ```bash # 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.