migrate-to-vinext

Next.js から vinext への移行

vinext は Vite 上で Next.js の API サーフェスを再実装しています。既存の app/、pages/、next.config.js はそのまま動作します。移行では、パッケージの入れ替え、設定の生成、ESM への変換を行います。アプリケーションコードを変更する必要はありません。

最初に：Next.js プロジェクトであることを確認する

package.json の dependencies または devDependencies に next があることを確認します。見つからない場合は、このスキルは適用されないため、作業を中止してください。

ロックファイルからパッケージマネージャーを判定します。

ロックファイル	マネージャー	インストール	アンインストール
pnpm-lock.yaml	pnpm	pnpm add	pnpm remove
yarn.lock	yarn	yarn add	yarn remove
bun.lockb / bun.lock	bun	bun add	bun remove
package-lock.json またはなし	npm	npm install	npm uninstall

ルーターを判定します。ルートまたは src/ 配下に app/ ディレクトリがある場合は、App Router です。pages/ のみがある場合は、Pages Router です。両方を併用することもできます。

クイックリファレンス

コマンド	用途
vinext check	プロジェクトをスキャンして互換性の問題を確認し、スコア付きレポートを作成します
vinext init	自動移行を行います。依存関係をインストールし、設定を生成し、ESM に変換します
npx vite dev	HMR 対応の開発サーバー
npx vite build	本番ビルド（App Router では複数環境に対応）
vinext start	ローカルの本番サーバー
npx @vinext/cloudflare deploy	Cloudflare Workers 向けにビルドしてデプロイします
vp exec vinext-cloudflare deploy	Vite+ を使って Cloudflare Workers 向けにビルドしてデプロイします

フェーズ 1：互換性を確認する

vinext check を実行します（必要に応じて、まず npx vinext check で vinext をインストールします）。スコア付きレポートを確認します。重大な非互換性がある場合は、続行する前にユーザーに知らせてください。

対応・非対応の機能と、エコシステムのライブラリの状況については、references/compatibility.md を参照してください。

フェーズ 2：自動移行（推奨）

vinext init を実行します。このコマンドは次の処理を行います。

1. 互換性レポートを作成するために vinext check を実行します
2. vite を devDependency としてインストールします（App Router の場合は @vitejs/plugin-rsc もインストールします）
3. package.json に "type": "module" を追加します
4. ESM との競合を避けるため、CJS 設定ファイルの名前を変更します（例：postcss.config.js → .cjs）
5. package.json に dev:vinext と build:vinext のスクリプトを追加します
6. 最小構成の vite.config.ts を生成します
7. .gitignore に /dist/ と .vinext/ を追加します

この処理は既存の設定を破壊しません。既存の Next.js 設定は vinext と並行して引き続き動作します。完全に切り替える前に、dev:vinext スクリプトを使ってテストしてください。

vinext init が成功した場合は、フェーズ 4（検証）に進んでください。失敗した場合、またはユーザーが手動での制御を希望する場合は、フェーズ 3 に進みます。

フェーズ 3：手動移行

vinext init が動作しない場合や、ユーザーが完全な制御を希望する場合の代替手順として使用します。

3a. パッケージを入れ替える

# Example with npm:
npm uninstall next
npm install vinext
npm install -D vite
# App Router only:
npm install -D @vitejs/plugin-rsc

3b. スクリプトを更新する

package.json のスクリプト内にあるすべての next コマンドを置き換えます。

変更前	変更後	備考
next dev	vite dev	HMR 対応の開発サーバー
next build	vite build	本番ビルド
next start	vinext start	ローカル本番サーバー
next lint	vinext lint	eslint/oxlint に処理を委譲します

Vite と互換性のあるフラグは維持します。next dev --port 3001 → vite dev --port 3001 のようにします。Next 専用のビルドフラグは Vite に渡すのではなく、vite.config.ts の vinext() オプションに変換します。

3c. ESM に変換する

package.json に "type": "module" を追加します。CJS の設定ファイルがあれば、名前を変更します。

• postcss.config.js → postcss.config.cjs
• tailwind.config.js → tailwind.config.cjs
• module.exports を使用するその他の .js 設定ファイル

3d. vite.config.ts を生成する

ルーターやデプロイ先ごとの設定例については、references/config-examples.md を参照してください。

プロジェクトにすでにカスタム Vite 設定がある場合は、編集時に Vite 8 ネイティブのキー（oxc、optimizeDeps.rolldownOptions、build.rolldownOptions）を優先してください。以前の esbuild と build.rollupOptions の設定も現時点では引き続き動作しますが、移行対象です。

Pages Router（最小構成）：

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

App Router（最小構成）：

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

rsc オプションが明示的に false に設定されていない場合、vinext は App Router 用の @vitejs/plugin-rsc を自動登録します。ローカル開発では、RSC プラグインを手動で設定する必要はありません。

3e. .gitignore を更新する

vinext が生成する出力とキャッシュが無視されるようにします。

/dist/
.vinext/

フェーズ 4：デプロイ（任意）

オプション A：Cloudflare Workers（Cloudflare に推奨）

Cloudflare Workers にデプロイする場合は、npx @vinext/cloudflare deploy を使用します。Vite+ では、ローカルにインストールされたバイナリを実行する際に vp exec vinext-cloudflare deploy を使用します。wrangler を介してビルドとデプロイを行います。

手動設定やカスタムワーカーエントリについては、references/config-examples.md を参照してください。

Cloudflare バインディング（D1、R2、KV、AI など）

Cloudflare バインディング（D1、R2、KV、AI、Queues、Durable Objects など）にアクセスするには、サーバーコンポーネント、ルートハンドラー、サーバーアクションのいずれかで import { env } from "cloudflare:workers" を使用します。

import { env } from "cloudflare:workers";

export default async function Page() {
  const result = await env.DB.prepare("SELECT * FROM posts").all();
  return <div>{JSON.stringify(result)}</div>;
}

@cloudflare/vite-plugin は workerd でサーバー環境を実行し、そこで cloudflare:workers がネイティブモジュールとして利用できるため、これは動作します。カスタムワーカーエントリも、getPlatformProxy() も、特別な設定も必要ありません。インポートして使用するだけです。

バインディングは wrangler.jsonc で定義する必要があります。TypeScript 型を生成するには、wrangler types を実行します。

重要： バインディングへのアクセスに getPlatformProxy()、getRequestContext()、または fetch(request, env) を使用するカスタムワーカーエントリを使用しないでください。これらは古いパターンです。cloudflare:workers が推奨される方法であり、vinext ですぐに使用できます。

オプション B：その他のプラットフォーム（Nitro 経由）

Vercel、Netlify、AWS、Deno Deploy、またはその他の Nitro 対応プラットフォームにデプロイするには、Nitro Vite プラグインを追加します。

npm install nitro

// vite.config.ts
import { defineConfig } from "vite";
import vinext from "vinext";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [vinext(), nitro()],
});

ビルドしてデプロイします。

NITRO_PRESET=vercel npx vite build    # Vercel
NITRO_PRESET=netlify npx vite build   # Netlify
NITRO_PRESET=deno_deploy npx vite build  # Deno Deploy
NITRO_PRESET=node npx vite build      # Node.js server

ほとんどの CI/CD 環境では Nitro がプラットフォームを自動検出するため、プリセットは不要なことがよくあります。

注： Cloudflare Workers では Nitro も動作しますが、cloudflare:workers バインディング、KV キャッシュ、ワンコマンドでのデプロイを利用して最適な開発体験を得るには、ネイティブ統合（npx @vinext/cloudflare deploy / vp exec vinext-cloudflare deploy / @cloudflare/vite-plugin）が推奨されます。

フェーズ 5：検証

1. 生成された dev:vinext スクリプト（または npx vite dev）を実行して、開発サーバーを起動します
2. サーバーがエラーなく起動することを確認します
3. 主要なルートにアクセスし、機能を確認します
4. 結果をユーザーに報告します。エラーが発生した場合は、出力全体を共有します

よくある移行エラーについては、references/troubleshooting.md を参照してください。

既知の制限事項

機能	状態
next/image optimization	@unpic 経由のリモート画像に対応。ビルド時の最適化はありません
next/font/google	CDN から読み込まれます。セルフホストには対応していません
Domain-based i18n	対応していません。パスプレフィックス方式の i18n は利用できます
next/jest	対応していません。Vitest を使用してください
Turbopack/webpack config	無視されます。代わりに Vite プラグインを使用してください
runtime / preferredRegion	配置設定は無視されます。cacheComponents の外では、エッジ App Router ページで ISR がスキップされます
PPR (Partial Prerendering)	代わりに "use cache" ディレクティブを使用してください（Next.js 16 の方式）

アンチパターン

• app/、pages/、またはアプリケーションコードを変更しないでください。 vinext はすべての next/* インポートをシムするため、インポートを書き換える必要はありません。
• アプリケーションコード内の next/* インポートを vinext/* に書き換えないでください。 next/image、next/link、next/server などのインポートは自動的に解決されます。
• webpack/Turbopack の設定を Vite の設定にコピーしないでください。 代わりに Vite ネイティブのプラグインを使用してください。
• 互換性チェックを省略しないでください。 問題を早期に見つけるため、移行前に vinext check を実行してください。
• next.config.js を削除しないでください。 next.config.ts または .mjs に置き換える場合を除きます。vinext はリダイレクト、リライト、ヘッダー、basePath、i18n、画像、環境設定の読み込みにこのファイルを使用します。
• バインディングに getPlatformProxy() やカスタムワーカーエントリーを使用しないでください。 代わりに import { env } from "cloudflare:workers" を使用してください。これは最新の方式であり、vinext と @cloudflare/vite-plugin でそのまま動作します。
• Cloudflare Workers では、Nitro よりネイティブ統合を優先してください。 npx @vinext/cloudflare deploy / vp exec vinext-cloudflare deploy / @cloudflare/vite-plugin は、cloudflare:workers バインディング、KV キャッシュ、画像最適化において最適なエクスペリエンスを提供します。Nitro も Cloudflare で動作しますが、ネイティブ構成を推奨します。