既存プロジェクトをVite+に移行する方法

既存プロジェクトをVite+に移行するには、新しいブランチを作成し、プロジェクトまたはワークスペースのルートで vp migrate を実行します。ファイルが変更される前に表示される移行計画を確認してください。移行後は vp install、vp check、vp test、vp build(ライブラリの場合は vp pack)で結果を検証し、そのうえでCIを更新します。

5つのツール設定が個別に存在する稼働中のリポジトリを新しいツールチェーンに移行する作業は、PRのタイトルだけ見ると小さな変更に見えますが、実際にはスプリントを丸ごと消費しがちです。問題が表面化するのは、たいてい自動化された処理が終わった後です。何が変換され、何が変換されなかったのかを把握するところから苦労が始まります。

本ガイドは、すでにVite、Vitest、ESLint、Prettierを使用しているプロジェクトを対象としています。vp migrate が何を変更し、何を手作業として残すのか、移行後に何を確認すべきか、そしてGitHub ActionsとGitLab CIをどう更新するかを解説します。Vite+とそのコマンドの概要を先に把握したい場合は、Getting Started with Vite+ から読み始めてください。Vite+ 1.0は2026年9月28日にリリースされており、MITライセンスで提供されています。

Vite+への移行が適しているのはどんなチームか、何が得られるのか

移行が適しているのは、Vite、Vitest、ESLint、Prettier、そしてtsupやtsdownといったライブラリバンドラーの設定を個別に管理しているチームです。移行後は依存関係が vite-plus 1つにまとまり、dev、test、lint、format、packの設定を1つの vite.config.ts で管理できるようになります。tsupはサポート対象の移行元なので、tsupでバンドルしているTypeScriptライブラリも移行できます。ただし、追加の作業が発生することは想定しておいてください。移行ガイドにも、ほとんどのプロジェクトではコマンド完了後に何らかの手動調整が必要であると明記されています。

vp migrateを実行する前に必要なもの

Vite+への移行は、クリーンなワーキングツリーから専用のブランチを作成して実行してください。そうすれば差分には移行による変更だけが含まれ、不要になった場合も簡単に破棄できます。

git switch -c chore/migrate-vite-plus
git status   # should report a clean tree

開始前に、次の3点を確認してください。

• Vite 7以降。 古いプロジェクトは、先にViteをアップグレードする必要があります。このリリースでの変更点は What’s New in Vite 7 で解説しています。
• Vitest 4以降。 古いテストスイートは、移行前にv4へアップグレードしてください。
• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0(Vitest 5アップグレードガイドによる)。

上流ツールのアップグレードが必要な場合は先に実施して動作を検証し、その後は既存のロックファイルとインストール済みパッケージをそのまま維持してください。移行ツールはこれらを読み取り、移行元のVitestのバージョンを判定します。

vp migrateを実行し、移行計画を確認する

引数なしで vp migrate を実行すると、カレントディレクトリが移行されます。ファイルを書き込む前に、予定している変更内容が表示されます。別のディレクトリにあるプロジェクトを移行する場合は、パスを指定してください。

vp migrate                    # interactive, migrates the current directory
vp migrate ./path/to/project  # migrate another directory
vp migrate --no-interactive   # scripted runs

migrateコマンドでは、次のフラグを使用できます。

• --no-interactive:プロンプトなしで実行します。
• --agent <name> / --no-agent:コーディングエージェント向けの指示ファイルを設定するかどうかを制御します。
• --editor <name> / --no-editor:エディター設定を書き込むかどうかを制御します。
• --hooks / --no-hooks:Gitフックを設定するかどうかを制御します。

モノレポでは、vp migrate の実行対象として有効なのはワークスペースのルートだけです。このコマンドが書き換えるロックファイル、カタログ、パッケージマネージャーの設定はワークスペース内のすべてのパッケージに属しているため、ルートから1回だけ実行してください。パッケージごとに実行してはいけません。

vp migrateが変換するもの、変換しないもの

vp migrate は依存関係を更新し、インポートを書き換え、ツールの設定を vite.config.ts に統合し、package.json のスクリプトを更新したうえで、変更したファイルをフォーマットします。既存のGitフックツールは、意図的に変更せずに残します。

テストのインポートは、上流のVitestから、Vitest 5を同梱する vite-plus の再エクスポートに切り替わります。一方、型拡張(augmentation)は引き続き上流の vitest を対象とします。

// before
import { defineConfig } from 'vitest/config'
import { describe, it, expect } from 'vitest'

// after
import { defineConfig } from 'vite-plus'
import { describe, it, expect } from 'vite-plus/test'

declare module 'vitest' {
  // unchanged: augmentations keep targeting upstream vitest
}

フックツールを残す場合は、lint-stagedもそのまま残ります。vp staged が読み取るのは vite.config.ts の staged ブロックだけだからです。vp staged への切り替えは手動で行います。

import { defineConfig } from 'vite-plus'

export default defineConfig({
  staged: {
    '*.{js,ts,tsx}': 'vp check --fix',
  },
})

0.23より古いtsdownを使用しているライブラリ(またはインストール済みのバージョンを特定できない場合)では、移行処理は従来のデフォルト値を維持します。具体的には、未設定であれば pack ブロックに deps.resolveDepSubpath: true を追加し、ATTWチェックが有効でプロファイルが未設定であれば attw.profile: 'strict' を追加します。変換内容の全体は移行ルールに記載されています。

移行後のプロジェクトを検証する方法

vp install、vp check、vp test、vp build(ライブラリの場合は vp pack)を実行し、コミット前にそれぞれの結果を確認してください。移行処理は変更したファイルに対してフォーマッターを実行するため、フォーマットの変更は、依存関係・設定・インポートの変更とは分けてレビューしましょう。そうしないと、再フォーマットによる差分にロジックの変更が埋もれてしまう可能性があります。

コミット前に、移行処理が出力するレビューレポートに目を通してください。ブラウザモード、カバレッジ、ベンチマークのテストスイートを運用している場合は、それらも個別に実行してください。

lintやフォーマットのルールが引き継がれない場合は

移行処理は、可能な範囲でESLintのflat configをOxlintに、Prettierの設定をOxfmtに変換しますが、すべてのESLintルールにOxlintの対応ルールがあるわけではありません。vp migrate はスキップしたサポート対象外のルールを一覧表示します。必要なルールが引き継がれなかった場合は、元のツールをプロジェクトスクリプトとして残し、vp run 経由で実行してください。

{ "scripts": { "lint:eslint": "eslint ." } }

vp run lint:eslint

この方法が使えるのは、ESLintのスクリプトが移行後も残っている場合に限られます。具体的には、ESLint/Prettierの変換プロンプトで変換を拒否した場合か、レガシーな .eslintrc を使用している場合です。それ以外の場合は、移行後にパッケージ、設定、スクリプトを手動で追加し直してください。なお、vp test は常に組み込みのテストコマンドを実行しますが、vp run test は package.json に定義された test スクリプトを実行します。

Nodeやパッケージマネージャーが意図しないバージョンに解決される場合は、vp env doctor を実行して原因を診断してください。

Vite+に合わせてCIを更新する方法

CIでは、Vite+のセットアップアクションが、Node、パッケージマネージャー、インストール、キャッシュの個別ステップを置き換え、ジョブからは vp コマンドを直接呼び出します。GitHub Actionsでは、run-install: false を設定しない限り、setup-vp が依存関係のインストールまで行います。

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: voidzero-dev/setup-vp@<setup-vp-version>
        with:
          node-version: '24'
          cache: true
      - run: vp check
      - run: vp test
      - run: vp build

GitLabでは、CIガイドに従い、リモートの setup-vp.yml テンプレートをincludeして .setup-vp をextendし、Nodeがあらかじめ含まれているイメージを使用します。

include:
  # copy the exact remote URL from the Vite+ CI guide
  - remote: 'https://raw.githubusercontent.com/voidzero-dev/setup-vp/<setup-vp-version>/gitlab/setup-vp.yml'
    inputs:
      setup-ref: '<setup-vp-version>'

check:
  extends: .setup-vp
  image: node:24
  # caching uses GitLab's native cache: keyword
  script:
    - vp check
    - vp test
    - vp build

setup-vpは v1 ではなく、正確なリリースタグまたはコミットSHAで固定してください。VoidZeroはこのタグをすでに更新していません。ワークフロー内の setup-vp@v1 を検索して置き換えましょう。GitLabではバージョンが2か所(includeのURLと setup-ref)に記述されているため、アップグレード時には両方を手動で更新する必要があります。

まとめ

Vite+への移行をスムーズに進めるコツは、vp migrate を作業のすべてではなく最初のステップとして捉えることです。移行計画を確認し、フォーマットの変更とロジックの変更を分けてレビューし、4つの検証コマンドを実行し、マージ前にCIでsetup-vpのバージョンを固定しましょう。次のステップとして、ブランチを作成して vp migrate を実行し、フックやlintルールについて表示される警告を一つずつ確認してください。

よくある質問

すでにVite+を使用しているプロジェクトでvp migrateを実行するとどうなりますか?

ツールチェーンのアップグレードのみを行います。すべてのワークスペースパッケージの依存関係とパッケージマネージャーの設定を、移行を実行しているCLIに同梱されたバージョンに更新し、インポートを最終的な形に整えます。Gitフック、エディターやエージェント向けのファイル、lintの移行といった初回セットアップはスキップされます。これらのセットアップ処理も実行したい場合は --full を指定してください。グローバルCLIに最新の移行ルールを反映させるため、事前に vp upgrade を実行しておきましょう。

プロジェクト自身のnode_modulesからvp migrateを実行すべきですか?

いいえ。Vite+の移行ガイドでは、古いプロジェクトの node_modules/.bin/vp を使って移行を実行しないよう明記されています。グローバルの vp を使用するか、npx --package=vite-plus@version vp migrate またはそれに相当する pnpm dlx コマンドで対象のリリースを取得してください。こうすることで、プロジェクトの古い依存関係を先に置き換えることなく対象のCLIを読み込めるため、移行ツールが移行元のVitestのバージョンを判定できます。

移行後のVite+はどのパッケージマネージャーに対応していますか?

Vite+はpnpm、npm、Yarn、Bunに対応しています。packageManagerフィールドやロックファイルなど、ワークスペースのルートにあるファイルからパッケージマネージャーを検出し、何も見つからない場合はpnpmにフォールバックします。その後 vp install は、適切なロックファイル関連のフラグも含め、検出されたパッケージマネージャーに対応するインストール処理を実行します。

移行によって削除されたESLintルールを確認するにはどうすればよいですか?

vp migrate は、Oxlintへの変換時にスキップしたサポート対象外のESLintルールを報告します。この機能はVite+ 0.3.2で追加されたもので、失われるチェック項目を確認できるようになっています。コミット前にその一覧に目を通し、必要なルールがあれば、ESLintをプロジェクトスクリプトとして残し vp run 経由で実行する形で再追加してください。