next-upgrade

next-upgradeスキルの概要

next-upgradeでできること

next-upgradeスキルは、実運用中の Next.js プロジェクトを新しいメジャーバージョンへ上げる際に、記憶頼みで推測するのではなく、公式の移行ガイドと codemod に沿って進められるよう支援するスキルです。役割は実務的で、まずアプリ内の現在の next バージョンを特定し、最も安全なアップグレード経路を整理し、先に適切な codemod を適用し、その後で依存関係を更新し、最後に手作業で直すべき breaking changes を洗い出します。

どんな人にnext-upgradeスキルが向いているか

この next-upgrade スキルは、既存の Next.js コードベースを保守していて、公式ガイダンスから大きく逸れずに AI アシスタントにアップグレード計画や実作業を任せたい開発者に特に向いています。とくに次のような場合に有効です。

• プロジェクトが最新より 1 つ以上前のメジャーバージョンに取り残されている
• 汎用的なチェックリストではなく、リポジトリの実態を踏まえたアップグレード計画がほしい
• バージョンごとの codemod や依存関係の整合性を特定したい
• ブラウザ上の要約ではなく、Code Editing ワークフローの中で支援を受けたい

実際に解決したい仕事

多くのユーザーが本当に必要としているのは「Next.js のアップグレード情報」そのものではありません。必要なのは、今は正常に動いているアプリを、新しい Next.js バージョンへ移行しつつ、ルーティング、React 互換性、ビルド出力、実行時 API を壊さないことです。next-upgrade は、その判断と実行の流れに焦点を当てたスキルです。

next-upgradeが普通のプロンプトと違う点

一般的なプロンプトでも広い意味でのアップグレード助言は出せますが、next-upgrade のほうが狙いが明確で実用的です。理由は、次の流れを前提に組まれているからです。

• 最初に package.json を読む
• 目標バージョンに対応する公式 Next.js アップグレードガイドを確認する
• メジャーバージョンを飛ばさず段階的に進める
• 手修正より先に公式 codemod を優先する
• next、react、react-dom の更新を正しく組み合わせる

このスキルが代わりにやってくれないこと

このスキルを使っても、検証作業は不要にはなりません。コード変更や依存関係更新の指針は示せても、最終的にはアプリの起動確認、テスト、lint、ビルド確認は自分で回す必要があります。また、monorepo、特殊な bundler 統合、サーバーや runtime を深くパッチしている構成のような、高度にカスタマイズされた環境では、フレームワーク固有の知識を置き換えるものでもありません。

next-upgradeスキルの使い方

next-upgradeのインストール前提

アップグレードしたいリポジトリ内で呼び出せるよう、AI コーディング環境にこのスキルを導入します。よくあるインストール方法は次のとおりです。

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

もし環境側で vercel-labs/next-skills の GitHub skill がすでに使える状態なら、next-upgrade をそのまま呼ぶだけで足りることもあります。

実務でのnext-upgradeの呼び出し方

リポジトリでは引数ヒントとして [target-version] が示されているため、最も素直な使い方は、目的のバージョンを明示することです。たとえば次のように指定します。

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

まだ目標バージョンを決めていない場合は、まず計画だけ出させるのが安全です。

• Use next-upgrade to inspect this repo and recommend the safest target version

next-upgradeに必要な入力

next-upgrade は、アシスタントが次の情報を確認できる状態だと最も力を発揮します。

• package.json
• package-lock.json、pnpm-lock.yaml、yarn.lock などの lockfile
• アプリが monorepo 内にある場合は workspace 設定
• ディレクトリ構成。特に app/ を使っているか pages/ を使っているか
• アップグレード後の検証に使う CI や build コマンド

最低限あると役立つ入力は次のとおりです。

• 現在の Next.js バージョン
• パッケージマネージャー
• 目標バージョン
• 計画だけほしいのか、実際のコード編集までしてほしいのか

ざっくりした依頼を強いnext-upgradeプロンプトに変える

弱いプロンプト:

• Upgrade my app

より良いプロンプト:

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

リポジトリが複雑な場合のベストなプロンプト:

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

このように具体性を足すほど出力品質は上がります。スキル自体は簡潔なので、リポジトリの範囲、パッケージマネージャー、実行範囲はプロンプト側で補うのが効果的です。

編集前におすすめのnext-upgradeワークフロー

信頼しやすい next-upgrade usage の流れは次のとおりです。

1. package.json と現在の依存関係バージョンを確認する
2. 目標バージョンを決める
3. 関係する各メジャーステップについて公式 Next.js アップグレードガイドを取得する
4. 手修正の前に codemod を実行する
5. next、react、react-dom を更新する
6. lint、typecheck、tests、本番 build を実行する
7. ガイドや runtime エラーで判明した残りの breaking changes を修正する

何バージョンも遅れている場合は、いきなり飛ばさないことが重要です。13 -> 14 -> 15 -> 16 のように、別々のアップグレード段階として処理するようアシスタントに指示してください。

最初に読むべきリポジトリファイル

まずは upstream リポジトリの skills/next-upgrade/SKILL.md を確認するのが出発点です。

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

このスキルは短く、周辺ファイルは多くありません。主な価値は SKILL.md に書かれたワークフローそのものにあります。つまり、バージョンを検出し、公式ドキュメントを取得し、段階的にアップグレードし、先に codemod を実行し、その後で依存関係を更新するという流れです。

このnext-upgradeが依存している公式ドキュメント

このスキルは、公式の Next.js アップグレード資料を明示的に参照します。たとえば次のようなものです。

• codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
• バージョン別ガイド:
  • https://nextjs.org/docs/app/guides/upgrading/version-16
  • https://nextjs.org/docs/app/guides/upgrading/version-15
  • https://nextjs.org/docs/app/guides/upgrading/version-14

導入判断においてここは重要です。next-upgrade の品質は、エージェントが古いフレームワーク知識に頼るのではなく、実際にこれらのガイドを取りに行って従うかどうかに大きく左右されます。

codemodは最後ではなく先に実行する

next-upgrade guide の強みのひとつは、作業順序が明確なことです。エージェントには、まず公式 codemod を早い段階で走らせるよう求めています。
npx @next/codemod@latest <transform> <path>

スキル内で挙げられている例は次のとおりです。

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

この順序は重要です。codemod は、依存関係を先に上げてから手で直すよりも、反復的な breaking changes を速く安全に処理できることが多いためです。

明示的に依頼したい依存関係更新

next-upgrade を使うときは、peer dependencies をまとめて上げるよう依頼すると効果的です。このスキルは特に次のパターンを中心に据えています。
npm install next@latest react@latest react-dom@latest

pnpm や yarn を使っていても考え方は同じです。公式ガイドに別指示がない限り、next、react、react-dom は連動するセットとして扱うのが基本です。

Code Editingで使うnext-upgrade

Code Editing での next-upgrade は、計画だけでなく、ファイル確認と変更の両方を任せると特に有用です。相性のよい作業は次のようなものです。

• package.json の依存バージョン範囲を更新する
• codemod コマンドを適用する
• breaking changes の影響を受ける API を修正する
• 手動レビュー用に inline comments や移行サマリーを残す

逆に、リポジトリ内ファイルや外部ドキュメントにアクセスできない環境では有用性は下がります。このスキルの価値は、リポジトリ確認と公式ガイド取得を組み合わせられる点にあるからです。

実運用での制約とトレードオフ

next-upgrade は、規律ある進め方をしたいときに向いていますが、限界もあります。

• すべてのバージョン差分をローカルに持っているわけではなく、都度ガイド参照を前提としている
• 標準的な Next.js アプリには強いが、高度にカスタマイズされたインフラには強くない
• プロジェクト固有のテスト自動化は内蔵していない
• monorepo、サブアプリ、ルート以外の package ファイルでは、追加のプロンプトが必要になることがある

要するに、このスキルは当て推量を減らしてくれますが、プロンプト側で対象範囲を明確にする必要は残ります。

next-upgradeスキル FAQ

next-upgradeは汎用的なアップグレードプロンプトより良い？

たいていは yes です。再現性のあるアップグレード手順がほしいなら、next-upgrade のほうが向いています。汎用プロンプトでももっともらしい提案はできますが、内容が古くなることがあります。next-upgrade は、公式 migration guide、codemod、そしてプロジェクトファイルからのバージョン検出を軸にしている点が違います。

next-upgradeスキルは初心者でも使いやすい？

はい。ただし注意点がひとつあります。初心者は、まず planning mode で使うのがおすすめです。最初に次の内容を出させてください。

• 現在のバージョン検出
• 目標バージョンの提案
• 実行すべき codemod
• 手作業になりそうな変更点
• 検証チェックリスト

こうしておくと、編集を許可する前に内容を確認しやすくなります。

先に目標バージョンを決めておく必要はある？

いいえ。next-upgrade にリポジトリを調べさせて、安全な目標バージョンを提案させることもできます。ただし、プラットフォーム要件や依存関係の都合で必要なバージョンが決まっているなら、最初から指定したほうが計画はすっきりします。

next-upgradeを使わないほうがよいのはどんなとき？

次のようなケースでは next-upgrade は適していません。

• 既存アプリのアップグレードではなく、新規アプリ作成が目的
• 問題がバージョン移行とは無関係
• スタックが公式ドキュメントで扱われない独自 internals に依存している
• 必要なのが 1 行のコマンドだけで、正確なバージョン経路もすでに分かっている

next-upgradeは複数バージョンをまたぐ移行に対応できる？

はい。ただし段階的に進めるべきです。このスキルは、根拠なく一気に飛ぶより、メジャーバージョンごとに刻んで上げる方法を明確に優先しています。アプリがかなり古い場合は、段階的な計画と、各メジャーバージョンごとの確認ポイントを求めるのが安全です。

app routerのプロジェクトでしか使えない？

いいえ。ただし、このスキルが取得する公式ガイドは、新しめの Next.js パターンを中心に説明していることがあります。コードベースが古い慣習を多く残しているなら、編集前に「ガイドのどこが適用対象で、どこは対象外か」をアシスタントに整理させるのが大切です。

next-upgradeスキルを改善する方法

next-upgradeにリポジトリ境界を明確に伝える

結果を最も早く改善できるのは、Next.js アプリがどこにあるかを正確に伝えることです。monorepo なら次の点を明示してください。

• apps/web のようなアプリパス
• パッケージマネージャー
• workspace ツール
• 変更範囲をそのアプリ内だけに限定するかどうか

これがないと、スキルが別の package.json を見たり、階層を誤ったコマンドを提案したりする可能性があります。

出力を2段階に分けて依頼する

有効なパターンは次の 2 段階です。

1. 計画のみ
2. 編集を実行

例:

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

こうすると、広すぎる変更を誤って入れるリスクを抑えられ、本番コードベースでも next-upgrade を信頼しやすくなります。

検証条件をより具体的に伝える

単に「正常にアップグレードして」と頼むのでは足りません。次のような具体的コマンドで検証するよう依頼してください。

• install
• lint
• typecheck
• unit tests
• production build

これにより next-upgrade usage の質が上がります。依存行だけ更新された状態ではなく、リポジトリが通る状態を目標に動けるためです。

何を失敗パターンとして避けたいか先に伝える

特定のリグレッション回避を重視するなら、それを明言してください。たとえば次のような指定です。

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

こうした制約があるほうが、単に「動くようにして」よりも、はるかに良い編集結果につながります。

codemod選定の理由も説明させる

次のような改善プロンプトは有効です。

• List which @next/codemod transforms apply to this repo and why before running them

これにより、エージェントが実際のコードパターンに合わせて transform を選んでいるのか、それとも無差別に codemod を回そうとしているのかをレビューしやすくなります。

next-upgradeでよくある失敗パターン

結果が弱くなりがちな典型例は次のとおりです。

• 現在のバージョン確認をせずに依存関係を上げる
• 中間のメジャーバージョンを飛ばす
• codemod の確認前に手修正を始める
• react と react-dom の整合性を無視する
• monorepo でルートの package.json をアプリ本体だと決めつける

こうした兆候が見えたら、作業を止めてバージョンごとの計画を出し直させるべきです。

最初の出力後にどう改善していくか

最初のパスのあとで、失敗した箇所に絞って 2 回目のパスを依頼すると効果的です。

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

ゼロからやり直すより、このやり方のほうが適しています。next-upgrade は一発で完璧に仕上げることより、移行ステップに沿って詰めていく使い方に向いているからです。

より高品質なnext-upgrade結果を得るためのベストなプロンプト

短くても情報量の多いテンプレートは次のとおりです。

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

このプロンプトなら、next-upgrade skill が汎用的な Code Editing 依頼より一段実用的な出力を返すために必要な構造が、ひと通り揃います。