svelte-cli

Svelte CLI (sv)

このスキルを使用する場面

ユーザーが次のことを求めている場合に、このスキルを使用します。

• 新しい SvelteKit プロジェクトを作成する（sv create）
• 既存のプロジェクトにインテグレーションを追加する（公式またはコミュニティのアドオンを使った sv add）
• Svelte プロジェクトで型／コンパイル／a11y の診断を実行する（sv check）
• Svelte／SvelteKit のバージョン間でコードベースを移行する（sv migrate）
• カスタムの sv アドオンをビルド、テスト、公開する
• sv-utils を使って svelte.config.js／vite.config.js をプログラムから読み取る、または編集する

一般的な Svelte コンポーネント API に関する質問、ルーティングの規約、ストア／状態管理にはこのスキルを使用しないでください。これらには svelte／sveltekit スキルを使用します。

概要 — sv とは？

sv は、Svelte（SvelteKit）アプリケーションの作成と保守に使用する、Svelte 公式のコマンドラインツールキットです。npm パッケージとして提供されており、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>

プロジェクトに sv がすでに devDependency として含まれている場合はローカルのコピーが使用されます。含まれていない場合は、一時的にダウンロードして実行されます。

サブコマンドは5つあります。

コマンド	用途
create	新しい Svelte（Kit）プロジェクトとオプションのアドオンをひな形から作成する
add	アドオン（公式またはコミュニティのもの）をプロジェクトに適用する
check	svelte-check による型／コンパイル／a11y の診断
migrate	codemod 移行スクリプト（svelte-migrate）を実行する
（プログラムからの使用）	sv.create、sv.add、defineAddon、defineAddonOptions

npx sv を実行しても何も起きないように見える場合は、「クイック修正」セクションを参照してください。これは、ダウンロードしたツールよりローカルのツールが優先される、既知の npm／yarn の動作です。

sv create

npx sv create [options] [path]

新しい SvelteKit プロジェクトをひな形から作成します。path を省略すると、空でないことが確認されたうえで（--no-dir-check を指定した場合を除く）、現在のディレクトリが使用されます。

オプション

フラグ	説明
--from-playground <url>	svelte.dev/playground の URL からプロジェクトを作成する
--template <name>	minimal、demo、または library
--types <option>	ts（.ts + lang="ts" がデフォルト）または jsdoc
--no-types	型チェックをスキップする
--add [add-ons...]	アドオンを事前に選択する（sv add と同じ構文）
--no-add-ons	対話形式のアドオン選択をスキップする
--install <pm>	npm／pnpm／yarn／bun／deno
--no-install	依存関係のインストールをスキップする
--no-dir-check	空でないターゲットディレクトリを許可する

よく使われる実行方法：

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

既存の Svelte（SvelteKit）プロジェクトに新しい機能を追加します。複数のアドオンはスペース区切りで指定できます。アドオンを指定しない場合は、対話形式のプロンプトが表示されます。

sv add のオプション

フラグ	説明
-C、--cwd <path>	プロジェクトのルート
--no-git-check	コミットされていない変更についての警告を無効にする
--no-download-check	コミュニティアドオンのダウンロードに関する警告を無効にする
--install <pm>	npm／pnpm／yarn／bun／deno
--no-install	依存関係のインストールを行わない

公式アドオン

位置引数として渡します。オプションは + で区切った key:value 構文を使います。

アドオン	追加される機能
better-auth	Drizzle アダプターを使った完全な認証設定。メールアドレス／パスワード認証と、オプションの GitHub OAuth デモページ
drizzle	postgresql ／ mysql ／ sqlite 用の ORM のひな形と、.env、オプションの Docker
eslint	ESLint のフラット設定と eslint-plugin-svelte。TS および prettier と連携
experimental	Svelte／SvelteKit の実験的フラグ、および／または @next 系統をオプトイン
mcp	AI エージェント向けの MCP サーバー設定（claude-code、cursor、vscode など）
mdsvex	Markdown プリプロセッサ（MDX スタイルの Svelte + Markdown）
paraglide	Vite プラグインと reroute ／ handle フックを使った Inlang Paraglide i18n
playwright	設定とデモテストを含むブラウザーテストランナー
prettier	.prettierrc と eslint との連携を含むフォーマッター
storybook	SvelteKit または Svelte+Vite 向けの Storybook
sveltekit-adapter	アダプター（auto、node、static、vercel、cloudflare、netlify）
tailwindcss	Tailwind v4 Vite プラグインと prettier との連携
vitest	ユニット／コンポーネントモードに対応した Vite ネイティブのテスト

オプションを指定する例：

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"

コミュニティアドオン

コミュニティアドオンは実験的です。API は変更される可能性があります。Svelte のメンテナーは、悪意のあるコードが含まれていないかコミュニティアドオンをレビューしていません。

コミュニティアドオンは、sv-add キーワードが付いた npm パッケージです。組織名（@org/sv を検索）、パッケージ名全体、file: パス、またはバージョンを指定して参照できます。

npx sv add @supacool                            # npm org lookup
npx sv add @my-org/[email protected]                     # 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

Windows PowerShell では、@ を引用符で囲んでエスケープします：npx sv add '@supacool'。

sv check

npm i -D svelte-check
npx sv check

svelte-check を実行します。.svelte、.svelte.ts、.svelte.js ファイル全体を対象に、未使用の CSS、a11y の問題、JS／TS のコンパイルエラーを検出します。Node 16 以降が必要です。

オプション

フラグ	説明
--workspace <path>	スキャンするワークスペース（デフォルト：プロジェクトのルート）
--output <format>	human、human-verbose、machine、machine-verbose
--watch	起動したままにして、変更時に再チェック
--preserveWatchOutput	watch モードで画面をクリアしない
--tsconfig <path>	特定の tsconfig／jsconfig を使用
--no-tsconfig	.ts／.js ファイルを完全にスキップ
--ignore <paths>	無視するパスをカンマ区切りで指定（--no-tsconfig と併用可能）
--fail-on-warnings	警告がある場合、ゼロ以外の値で終了
--compiler-warnings <pairs>	code:behaviour のペア。例：css_unused_selector:ignore
--diagnostic-sources <sources>	js（TS を含む）、svelte、css
--threshold <level>	warning（デフォルト）または error のみ

機械可読形式の出力

--output machine と --output machine-verbose は、スペース区切り／JSON 区切りの行ストリームを出力します。

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

machine-verbose バリアントは、start ／ end の位置、code、source、詳細な説明を含む ndjson を出力します。

svelte-check は「ステージされたファイルのみをチェックする」モードをサポートしていません。ファイル間の型エラーを正しく検出するには、プロジェクト全体を対象にする必要があります。

sv migrate

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

svelte-migrate に処理を委ねます。一部のマイグレーションでは、手作業で完了させる必要のある // @migration TODO がコードに追加されます。

マイグレーション	目的
app-state	.svelte ファイル内の $app/stores を $app/state に置き換え（SvelteKit 2.12 以降）
svelte-5	Svelte 4 から 5 へ：コンポーネントをルーン（$state、$derived、$effect、$props など）に変換
self-closing-tags	.svelte ファイル内の、自己終了形式になっている非 void 要素を置き換え
svelte-4	Svelte 3 から 4 へ
sveltekit-2	SvelteKit 1 から 2 へ
package	@sveltejs/package v1 から v2 へ（ライブラリの作者向け）
routes	リリース前の SvelteKit から SvelteKit 1 のファイルシステムルーティングへ

マイグレーションを実行する前に、必ずコミットしてください。差分を確認し、元に戻せるようになります。

カスタムアドオン（プログラム API）

アドオンシステムは、次の 2 つのパッケージで構成されています。

• sv — 場所とタイミングを担当します。ワークスペースの検出、ファイルの入出力、依存関係の追跡、アドオンのオーケストレーションを行います。
• @sveltejs/sv-utils — 処理内容を担当します。純粋なパーサー、AST 変換、言語ヘルパーを提供します。ファイルシステムは認識しません。

カスタムアドオンの基本構成：

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}!`]
});

ブートストラップ、バンドル（tsdown）、公開（npm org が必要）、テスト（sv/testing の createSetupTest）、および package.json のルールについては、references/custom-addon-reference.md を参照してください。

sv-utils（アドオン作成者向けの低レベル API）

@sveltejs/sv-utils は実験的ですが、アドオンが一般的に編集するすべてのファイル形式に対応した、パーサー対応の変換機能を提供します。

変換

各変換はカリー化された関数です。コールバックを渡して呼び出すと、sv.file() に渡せる (content) => content 関数が返されます。

変換	コールバックが受け取る値	用途
transforms.script	{ ast, comments, content, js }	.js / .ts ファイル
transforms.svelte	{ ast, content, svelte, js }	.svelte コンポーネント
transforms.svelteScript(opts, cb)	{ ast, content, svelte, js }（ast.instance は常に null 以外）	<script> の存在が保証されたコンポーネント
transforms.css	{ ast, content, css }	.css ファイル
transforms.json	{ data, content, json }	package.json、tsconfig.json
transforms.yaml / transforms.toml	{ data, content }	設定ファイル
transforms.text	{ content, text }	.env、.gitignore

コールバックから false を返すと処理を中止し、元のコンテンツを保持します。js.* / css.* / svelte.* / json.* / html.* / text.* ヘルパーの名前空間については、references/sv-utils-reference.md を参照してください。

Svelte 設定ヘルパー

SvelteKit の設定は、vite.config.{js,ts}（sveltekit() プラグインの引数を介して）または svelte.config.{js,ts} に記述できます。svelteConfig.edit はどちらにも透過的に書き込むため、kit のネストを自分で扱う必要はありません。

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) は { path, kind }（'vite' または 'svelte'）を返します。svelteConfig.read(read) は { location, config, kit } オブジェクト式を返します。

パッケージマネージャーヘルパー

pnpm.allowBuilds('pkg-name') は、パッケージを pnpm の allow-builds 設定に追加する pnpm-workspace.yaml 用の変換を返します。インストールされている pnpm のバージョンを検出します。

• pnpm >= 11 -> 統合された allowBuilds: { pkg: true } マップ
• pnpm < 11 -> 従来の onlyBuiltDependencies リスト

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

よくある問題の解決方法

• npx sv を実行しても何も起きない — npm/yarn はローカルにインストールされたツールを優先します。解決方法：

  • npm exec sv ... または npx --yes sv ... を実行します。
  • Windows PowerShell では、sv が Set-Variable エイリアスと衝突します。sveltejs/cli#317 を参照してください。
  • Linux では、sv が runit と衝突する場合があります。sveltejs/cli#259 を参照してください。
  • 確認方法：npx --yes sv --version を実行すると、バージョンが表示されます。

• sv check が見つからない — 先に svelte-check をインストールします：npm i -D svelte-check。

• PowerShell で sv add @community がエラーになる — 引数を引用符で囲みます：npx sv add '@supacool'。

• 移行後に @migration TODO が残っている — 手動で対応する必要があります。// @migration を検索して解消してください。

• git が未コミットの変更を検出し、sv add が実行を拒否する — 変更があるツリーで意図的に作業している場合は、--no-git-check を渡します。

• svelte-check が JS/TS ファイルで失敗する — --tsconfig を指定するか、--no-tsconfig を使って対象から完全に除外します。

• sv add file:../path で変更が反映されない — demo-add スクリプトは自動で再ビルドします。それ以外の場合は、再実行する前にアドオンを再バンドルしてください。

注意点

• コミュニティアドオン API は実験的であり、変更される可能性があります。peerDependencies に sv のバージョンを固定してください（例："sv": "^0.13.0"）。
• コミュニティアドオンのパッケージは、npm の組織アカウント（@org/...）で公開する必要があります。my-lib のような通常の名前は拒否されます。
• パッケージ名の sv スコープは暗黙的に解決されます。npx sv add @my-org は npx sv add @my-org/sv と同じです。
• バンドルするアドオンには、tsdown が標準です。CLI はまず ./sv を探し、次に . を探します。そのため、アドオン以外の機能も公開するパッケージでは、./sv サブパス経由でアドオンを公開してください。
• sv check はファイルの一部（例：ステージング済みファイルのみ）に対しては実行できません。ファイル間の型エラーを正しく検出するには、プロジェクト全体が必要です。
• --ignore がファイルウォッチャーに対して有効になるのは、--no-tsconfig と併用した場合のみです。--tsconfig を指定した場合、無視するファイルは設定の exclude によって決まります。
• svelteConfig.edit は sv.file を介して書き込むため、編集内容はほかのすべての変更と同じ差分に表示されます。ファイルを手動で読み書きして、この仕組みを回避しないでください。
• transforms.yaml / transforms.toml は data を直接変更します。戻り値は無視されます。
• pnpm < 11 と >= 11 では、「ビルドを許可する」設定に異なるスキーマが使われます。ヘルパーはどちらにも対応しますが、直接記述する場合はバージョンごとのロジックに合わせてください。

よくある質問

Q：各パッケージマネージャーで sv を実行するにはどうすればよいですか？

PM	コマンド
npm	npx sv create
pnpm	pnpm dlx sv create
Bun	bunx sv create
Deno	deno run npm:sv create
Yarn	yarn dlx sv create

Q：すでに sv がインストールされているプロジェクト内から sv を実行できますか？

はい。npx sv ... は、ローカルにインストールされたコピーがあればそれを使用し、なければ最新バージョンを一時的にダウンロードします。そのため、インストール手順なしで sv create を実行できます。

Q：sv check --output の machine と machine-verbose はどう違いますか？

どちらも START / ERROR / WARNING / COMPLETED / FAILURE の行を出力します。machine の列は、タイムスタンプ、種類、ファイル名、行：列、メッセージです。machine-verbose では、終了位置、診断コード、ソースが追加され、各行は ndjson 形式になります。

Q：コミュニティアドオンをインストールしても安全ですか？

Svelte のメンテナーによるレビューは行われていません。自己責任でインストールしてください。--no-download-check を指定すると警告は抑制されますが、安全性が高まるわけではありません。

Q：sv check でステージング済みファイルだけをチェックできますか？

いいえ。svelte-check にはプロジェクト全体のグラフが必要です。一部だけをチェックすると、変更されていないファイル内の名前変更された prop の使用箇所を見落とします。

Q：svelte.config.js はどこに置けばよいですか？

vite.config.{js,ts} 内（sveltekit() プラグインに渡す）または、独立した svelte.config.{js,ts} として配置できます。sv create は vite.config.js 内に保持します。svelteConfig.edit はどちらにも透過的に対応します。

Q：カスタムアドオンに必要な sv の最小 peer dependency は何ですか？

コードで使用するバージョンを package.json の peerDependencies に設定してください。インストールされた sv のメジャーバージョンが異なる場合、ユーザーに互換性の警告が表示されます。リファレンスアドオンは sv@^0.13.0 を対象としています。

Q：sv add が未コミットの変更について警告するのはなぜですか？

複数のプロジェクトファイルを変更するためです。この警告は安全策です。回避するには --no-git-check を渡してください。