Svelte入門：リファレンス CLI -sv migrate-

よっしー

こんにちは。よっしーです(^^)

今日は、SvelteKitのリファレンスについて解説しています。

背景
CLIツール（sv）
おわりに

背景

SvelteKitのリファレンスについて調査する機会がありましたので、その時の内容を備忘として記事に残しました。

CLIツール（sv）

コマンドラインインターフェース（CLI）であるsvは、Svelteアプリケーションの作成と保守のためのツールキットです。

sv migrate とは

sv migrateコマンドは、Svelte(Kit)のコードベースを移行するためのツールです。このコマンドは内部的にsvelte-migrateパッケージを利用しています。

一部の移行プロセスでは、完了すべきタスクが@migrationというタグでコードベースに注釈付けされることがあります。これらは検索することで見つけることができます。

sv migrate の使用方法

基本的な使い方:

npx sv migrate

CLIから直接移行オプションを指定することも可能です:

npx sv migrate [migration]

app-state

.svelteファイル内の$app/storesの使用を$app/stateに移行します。詳細は移行ガイドを参照してください。

svelte-5

Svelte 4アプリをSvelte 5に更新し、個々のコンポーネントをルーンやその他のSvelte 5構文を使用するように更新します（移行ガイド参照）。

self-closing-tags

.svelteファイル内のすべての自己閉じ非void要素を置き換えます。詳細についてはプルリクエストを参照してください。

svelte-4

Svelte 3アプリをSvelte 4に更新します（移行ガイド参照）。

sveltekit-2

SvelteKit 1アプリをSvelteKit 2に更新します（移行ガイド参照）。

package

@sveltejs/packageバージョン1を使用しているライブラリをバージョン2に更新します。詳細についてはプルリクエストを参照してください。

routes

プレリリース版のSvelteKitアプリをSvelteKit 1で使用されているファイルシステムルーティング規則に更新します。詳細についてはプルリクエストを参照してください。

実践的なアドバイス

移行を実行する前に以下のポイントを確認しましょう:

プロジェクトのバックアップを作成する
移行前に依存関係を最新の状態に更新する
移行後は@migrationタグを検索して手動で対応が必要な箇所を確認する
すべての変更を適用した後、アプリケーションが正常に動作することをテストする

移行ツールは多くの変更を自動化してくれますが、完全な自動化ではないため、移行後の手動確認は重要です。特に大規模なプロジェクトや複雑な機能を持つアプリケーションでは注意が必要です。

1. インタラクティブな移行

npx sv migrate

このコマンドを実行すると、利用可能な移行オプションが表示され、対話形式で選択できます。例えば：

次の移行オプションから選択してください：
1. app-state: $app/storesから$app/stateへの移行
2. svelte-5: Svelte 4からSvelte 5への移行
3. svelte-4: Svelte 3からSvelte 4への移行
...

2. 特定の移行を直接指定

npx sv migrate svelte-5

これによりSvelte 4からSvelte 5への移行が直接開始されます。

3. Svelte 4からSvelte 5への移行

# プロジェクトディレクトリで実行
cd my-svelte-project
npx sv migrate svelte-5

実行結果：

Svelte 5への移行を開始します...
package.jsonを更新しています...
依存関係をアップデートしています...
コンポーネントファイルを更新しています...
$:宣言をrune構文に変換しています...
移行が完了しました。
@migrationタグで注釈付けされたタスクを確認してください。

4. SvelteKit 1からSvelteKit 2への移行

cd my-sveltekit-project
npx sv migrate sveltekit-2

実行結果：

SvelteKit 2への移行を開始します...
package.jsonを更新しています...
依存関係をアップデートしています...
ルーティング構造を確認しています...
サーバー関数を更新しています...
移行が完了しました。
@migrationタグで注釈付けされたタスクを確認してください。

5. 自己閉じタグの修正

cd my-svelte-project
npx sv migrate self-closing-tags

実行結果：

自己閉じタグの修正を開始します...
.svelteファイルをスキャンしています...
自己閉じ非void要素を修正しています...
(<div />を<div></div>に変換するなど)
修正が完了しました。

移行後のフォローアップ例

移行実行後、@migrationタグを検索して手動対応が必要な箇所を確認します：

# プロジェクト内で@migrationタグを検索
grep -r "@migration" .

検索結果の例：

./src/routes/+page.svelte:<!-- @migration task: この箇所は手動で確認が必要です - $:宣言がrune構文に正しく変換されているか確認してください -->
./src/lib/Components/Counter.svelte:<!-- @migration task: createEventDispatcherの使用方法をSvelte 5の新しいAPI形式に更新してください -->

これらの注釈を参考に、必要な手動修正を行います。

移行ツールはコードベースの大部分を自動的に更新してくれますが、特定のケースでは手動の確認や修正が必要です。特に複雑なコンポーネントや特殊な使用法がある場合は注意深く確認することをお勧めします。