svelte-cli

Svelte CLI (sv)

When to use this skill

Use this skill when the user wants to:

• Create a new SvelteKit project (sv create)
• Add an integration to an existing project (sv add with official or community add-ons)
• Run type / compile / a11y diagnostics on a Svelte project (sv check)
• Migrate a codebase between Svelte / SvelteKit versions (sv migrate)
• Build, test, and publish a custom sv add-on
• Read or edit svelte.config.js / vite.config.js programmatically via sv-utils

Do not use this skill for general Svelte component API questions, routing conventions, or store/state management — those belong to the svelte / sveltekit skills.

Overview — what is sv?

sv is the official Svelte command-line toolkit for creating and maintaining Svelte(SvelteKit) applications. It ships as an npm package and is best run via npx / pnpm dlx / bunx / deno run npm:sv:

npm       -> npx sv <command>
pnpm      -> pnpm dlx sv <command>
bun       -> bunx sv <command>
deno      -> deno run npm:sv <command>
yarn      -> yarn dlx sv <command>

If sv is already a devDependency in the project, the local copy is used; otherwise it is downloaded and run ephemerally.

Five subcommands:

If npx sv appears to do nothing, see the Quick Fixes section — this is a known npm/yarn behaviour where the local tool is preferred over downloading.

sv create

npx sv create [options] [path]

Scaffolds a new SvelteKit project. If path is omitted, the current directory is used (after a non-empty check, unless --no-dir-check is passed).

Options

Common invocation:

npx sv create --template minimal --types ts --add eslint prettier my-app

sv add

npx sv add [add-ons...]     # in a project
npx sv create --add ...     # during project creation

Updates an existing Svelte(SvelteKit) project with new functionality. Multiple add-ons can be space-separated. Interactive prompt runs if no add-ons are passed.

sv add options

Official add-ons

Pass them as positional args. Options use key:value syntax separated by +.

Example with options:

npx sv add tailwindcss="plugins:typography,forms"
npx sv add drizzle="database:postgresql+client:postgres.js+docker:yes"
npx sv add sveltekit-adapter="adapter:cloudflare+cfTarget:workers"

Community add-ons

Community add-ons are experimental. The API may change. Svelte maintainers have not reviewed community add-ons for malicious code.

Community add-ons are npm packages tagged with the sv-add keyword. Reference by org name (looks up @org/sv), full package name, file: path, or version:

npx sv add @supacool                            # npm org lookup
npx sv add @my-org/sv@1.2.3                     # pinned version
npx sv add file:../path/to/my-addon             # local add-on
npx sv add eslint @supacool                     # mix official + community
npx sv create --add eslint @supacool my-app

On Windows PowerShell, escape @ with quotes: npx sv add '@supacool'.

sv check

npm i -D svelte-check
npx sv check

Runs svelte-check: detects unused CSS, a11y issues, and JS/TS compile errors across .svelte, .svelte.ts, .svelte.js files. Requires Node 16+.

Options

Machine-readable output

--output machine and --output machine-verbose produce a stream of space/JSON-separated rows:

1590680325583 START "/path/to/workspace"
1590680326283 ERROR "codeaction.svelte" 1:16 "Cannot find module 'blubb'..."
1590680326778 WARNING "imported-file.svelte" 0:37 "Component has unused export property..."
1590680326807 COMPLETED 20 FILES 21 ERRORS 1 WARNINGS 3 FILES_WITH_PROBLEMS
1590680328921 FAILURE "Connection closed"   # only on runtime error

The machine-verbose variant emits ndjson with start / end positions, code, source, and full descriptions.

svelte-check does not support a "check only staged files" mode — it must see the whole project for cross-file type errors to be valid.

sv migrate

npx sv migrate                 # interactive picker
npx sv migrate [migration]     # run a specific codemod

Delegates to svelte-migrate. Some migrations annotate your code with // @migration TODOs you must complete by hand.

Always commit before running a migration so you can diff and revert.

Custom add-ons (programmatic API)

Two packages form the add-on system:

• `sv` — where and when: workspace detection, file I/O, dependency tracking, add-on orchestration.
• `@sveltejs/sv-utils` — what: pure parsers, AST transforms, language helpers. No filesystem awareness.

Skeleton of a custom add-on:

import { transforms } from '@sveltejs/sv-utils';
import { defineAddon, defineAddonOptions } from 'sv';

export default defineAddon({
  id: 'my-addon',
  shortDescription: 'says hello',
  options: defineAddonOptions()
    .add('who', { question: 'To whom?', type: 'string' })
    .build(),
  setup: ({ dependsOn, isKit, unsupported }) => {
    if (!isKit) unsupported('Requires SvelteKit');
    dependsOn('vitest');
  },
  run: ({ sv, options, directory }) => {
    sv.file(
      directory.kitRoutes + '/+page.svelte',
      transforms.svelte(({ ast, svelte }) => {
        svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
      })
    );
  },
  nextSteps: ({ options }) => [`Greet ${options.who}!`]
});

Bootstrapping, bundling (tsdown), publishing (npm org required), testing (sv/testing's createSetupTest), and package.json rules live in references/custom-addon-reference.md.

sv-utils (low-level API for add-on authors)

@sveltejs/sv-utils is experimental but provides parser-aware transforms for every file type an add-on commonly edits.

Transforms

Each transform is a curried function — invoke with a callback to get a (content) => content function, ready to pass to sv.file().

Return false from the callback to abort — original content is kept. See references/sv-utils-reference.md for the full js.* / css.* / svelte.* / json.* / html.* / text.* helper namespaces.

Svelte config helpers

SvelteKit config can live in vite.config.{js,ts} (via sveltekit() plugin arg) or in svelte.config.{js,ts}. svelteConfig.edit writes through both transparently — never deal with the kit nesting yourself:

import { svelteConfig } from '@sveltejs/sv-utils';

svelteConfig.edit({ sv, cwd }, ({ ast, property, override, js }) => {
  // svelte-level option
  js.array.append(property('extensions', { fallback: js.array.create() }), '.svx');
  // kit option
  override({ adapter: js.functions.createCall({ name: 'adapter', args: [], useIdentifiers: true }) });
});

svelteConfig.find(read) returns { path, kind } ('vite' or 'svelte'); svelteConfig.read(read) returns { location, config, kit } object expressions.

Package manager helpers

pnpm.allowBuilds('pkg-name') returns a transform for pnpm-workspace.yaml that adds the package to pnpm's allow-builds config. Detects installed pnpm version:

• pnpm >= 11 -> unified allowBuilds: { pkg: true } map
• pnpm < 11 -> legacy onlyBuiltDependencies list

if (packageManager === 'pnpm') {
  sv.file(file.findUp('pnpm-workspace.yaml'), pnpm.allowBuilds('esbuild'));
}

Quick Fixes

• `npx sv` does nothing — npm/yarn prefer locally-installed tools. Solutions:
• npm exec sv ... or npx --yes sv ...
• On Windows PowerShell, sv collides with Set-Variable alias — see sveltejs/cli#317.
• On Linux, sv may collide with runit — see sveltejs/cli#259.
• Confirm: npx --yes sv --version should print a version.

• `sv check` not found — install svelte-check first: npm i -D svelte-check.

• `sv add @community` errors on PowerShell — quote the arg: npx sv add '@supacool'.

• Migration left `@migration` TODOs — these are manual follow-ups; search for // @migration and complete them.

• `sv add` refuses because of dirty git — pass --no-git-check if you're intentionally working on a dirty tree.

• `svelte-check` fails on JS/TS files — either provide --tsconfig or use --no-tsconfig to skip them entirely.

• `sv add file:../path` not picking up changes — the demo-add script rebuilds automatically; otherwise re-bundle your add-on before re-running.

Gotchas

• Community add-on API is experimental and may break. Pin a sv version in peerDependencies (e.g. "sv": "^0.13.0").
• Community add-on packages must be published under an npm org (@org/...) — plain names like my-lib are rejected.
• The sv scope on the package name resolves implicitly: npx sv add @my-org == npx sv add @my-org/sv.
• For bundled add-ons, tsdown is the standard. The CLI looks for ./sv first, then . — so packages exporting other functionality alongside add-ons should expose the add-on via the ./sv subpath.
• sv check cannot run on a subset of files (e.g. staged only). It needs the whole project for cross-file type errors to be valid.
• --ignore only takes effect for the file watcher when paired with --no-tsconfig; with --tsconfig, ignore is determined by the config's exclude.
• svelteConfig.edit writes through sv.file, so the edit shows up in the same diff as every other change — don't bypass it by reading and writing the file manually.
• transforms.yaml / transforms.toml mutate data in place — return value is ignored.
• pnpm < 11 and >= 11 use different schemas for "allow builds" — the helper handles both, but if you write directly, mirror the version logic.

FAQ

Q: How do I run `sv` with each package manager?

Q: Can I run `sv` from inside a project that already has it installed?

Yes. npx sv ... will use the locally installed copy if present; otherwise it downloads the latest version ephemerally. This is why sv create works without any install step.

Q: What's the difference between `machine` and `machine-verbose` for `sv check --output`?

Both emit START / ERROR / WARNING / COMPLETED / FAILURE rows. machine columns are: timestamp, type, filename, line:col, message. machine-verbose adds end positions, diagnostic code, and source — each row as ndjson.

Q: Are community add-ons safe to install?

They are not reviewed by Svelte maintainers. Install at your own risk. --no-download-check suppresses the warning but does not add any safety.

Q: Can I check only staged files with `sv check`?

No. svelte-check requires the whole project graph. Checking a subset would miss renamed prop usages in unchanged files.

Q: Where should `svelte.config.js` live?

Either inside vite.config.{js,ts} (passed to the sveltekit() plugin) or as a separate svelte.config.{js,ts}. sv create keeps it in vite.config.js. svelteConfig.edit handles both transparently.

Q: What is the minimum `sv` peer dependency for a custom add-on?

Whatever your code uses — set it in package.json peerDependencies. Users get a compatibility warning if the installed sv has a different major version. Reference add-ons target sv@^0.13.0.

Q: Why does `sv add` warn about uncommitted changes?

Modifies multiple project files. The warning is a safety net; pass --no-git-check to bypass.