Nuxtは、Vue.jsを基盤としてWebサイトやWebアプリケーションを構築するためのフレームワークです。
Nuxt 4は2025年7月15日に正式リリースされ、現在はリリース候補版ではありません。
Nuxt 3からの移行で先に確認したいのは、app/を中心とするディレクトリ構成、データ取得の挙動、TypeScriptの設定、利用中のモジュールです。
NuxtとVue.jsの役割から整理したい場合は、Node.js、Vue.js、Nuxt.js、Next.jsの役割と使い分けも参考になります。
Nuxt 4の現在地
当初のロードマップでは、Nuxt 4をリリース候補版で検証した後に安定版へ進める方針が示されていました。
その後、Nuxt 4.0の公式リリースが発表され、移行時に確認すべき変更点は公式アップグレードガイドに集約されています。
| 段階 | 日付 | 位置づけ |
|---|---|---|
| ロードマップ公開 | 2025年6月2日 | Nuxt 4と、その後のNuxt 5を分けて進める方針を説明 |
| リリース候補版 | 2025年7月8日 | 機能を固め、安定版に向けた最終検証へ移行 |
| 安定版 | 2025年7月15日 | Nuxt 4.0を正式リリース |
Nuxt 5は、公式ガイド上で現在も開発中とされています。
過去の「数か月以内」という見通しを移行計画の締め切りとして扱わず、Nuxt 4の安定版と最新の公式ガイドを基準に判断してください。
Nuxt 4で確認したい主な変更点
app/を中心にしたディレクトリ構成
Nuxt 4では、アプリケーション側のコードをapp/配下に置く構成が標準になりました。
これはpages/の廃止を意味しません。
ページはapp/pages/へ移し、server/、public/、modules/などはプロジェクトのルートに残します。
project/
├─ app/
│ ├─ components/
│ ├─ composables/
│ ├─ layouts/
│ ├─ middleware/
│ ├─ pages/
│ ├─ plugins/
│ └─ app.vue
├─ public/
├─ server/
├─ shared/
└─ nuxt.config.tsアプリケーションコードとサーバーコードの置き場所が分かれるため、ファイル監視の対象を絞りやすくなり、開発環境がコードの文脈を判別しやすくなります。
一方、従来の構成にも後方互換性があるため、移行のためだけに全ファイルを一度に動かす必要はありません。
useAsyncDataとuseFetchの挙動
useAsyncDataとuseFetchは、サーバー側で取得したデータをクライアントへ渡し、画面の初期化時に同じ取得処理を繰り返さないための仕組みです。
Nuxt 4では、同じキーを使う複数の呼び出しがデータを共有し、コンポーネントの破棄に合わせた後処理も行われます。
「同じURLなら常に自動で一つのリクエストになる」と考えるのは正確ではありません。
キー、オプション、実行時期が異なれば挙動も変わるため、移行時は公式のデータ取得ガイドと実際の通信ログを照合します。
SSRの仕組み自体を確認したい場合は、SPA、SSR、SSGの違いと使い分けで基礎を整理できます。
TypeScriptの文脈分離
Nuxt 4は、アプリケーション、サーバー、共有コード、ビルド設定を別々のTypeScriptプロジェクトとして扱います。
これにより補完や型推論の精度が上がる一方、Nuxt 3では表面化しなかった型エラーが見つかることがあります。
型定義を追加しているプロジェクトでは、その定義がアプリケーション用か、サーバー用か、共有用かを確認します。
ルートのtsconfig.jsonだけを見て判断せず、型エラーが出たファイルの配置と実行環境を対応づけることが必要です。
ヘッド管理と開発ツール
Nuxt 4ではUnhead v2への移行に伴い、廃止予定だった機能の整理、タグ処理、開発時の性能が見直されました。
ただし、タイトルやメタディスクリプションが自動で最適化されるわけではありません。
useHeadやuseSeoMetaを使っているページは、生成されたHTMLでタグの内容と重複を確認します。
CLIの起動やファイル監視にも改善があります。
一方、Vite Environment APIはNuxt 5に向けた変更として扱われているため、Nuxt 4の移行効果として一括して見積もるのは避けます。
移行方針を決める判断表
| プロジェクトの状況 | 先に確認する内容 | 進め方 |
|---|---|---|
| 標準構成に近い小規模なサイト | 依存パッケージ、ビルド、主要画面 | Nuxtを更新し、既存構成のままテストしてからapp/移行を判断する |
独自のsrcDirを使っている |
server/、public/、modules/の解決位置 |
設定と実際の配置を対応表にし、一つずつ変更する |
| 外部モジュールが多い | 各モジュールのNuxt 4対応状況と設定変更 | 対応可否を確認し、代替手段か更新時期を決めてから本体を上げる |
| SSRで複数のAPIを利用している | データ取得キー、キャッシュ、エラー処理、ハイドレーション | ページ単位で通信回数とサーバー出力を比較する |
| 型拡張や独自プラグインが多い | 型定義の配置、プラグインの読込順、実行環境 | 型検査と実行時テストを分けて、不具合の原因を切り分ける |
Nuxt 3からNuxt 4へ移行する手順
- 現状を記録する作業用ブランチを作り、ロックファイル、現在のビルド結果、主要画面、API通信、環境変数の一覧を保存します。
元に戻せる基準を先に用意すると、Nuxt本体の変更と既存不具合を区別できます。 - モジュールと周辺パッケージを確認する利用中のNuxtモジュール、Vueプラグイン、ビルド関連パッケージがNuxt 4に対応しているかを確認します。
保守が止まった依存先がある場合は、本体更新より先に代替方法を決めます。 - Nuxtを更新する
公式リリース案内では、依存関係の重複も整理する次のコマンドが推奨されています。
npx nuxt upgrade --dedupe実行後は、変更されたロックファイルと警告を確認してから次へ進みます。
- 必要な範囲だけCodemodを使う
複数の移行処理をまとめて適用する場合は、公式案内にある次のレシピを利用できます。
npx codemod@latest nuxt/4/migration-recipeCodemodは移行作業の一部を自動化する道具であり、すべての独自実装を判断できるものではありません。
実行前後の差分を読み、意図しない変更がないかを確認します。 - ディレクトリを段階的に整理する
components/、composables/、layouts/、middleware/、pages/、plugins/などをapp/へ移します。
同時に、エイリアス、CSSやLintの設定、テストで参照しているパスも更新します。 - データ取得と型を検証する
useAsyncDataとuseFetchのキー、オプション、エラー処理を確認します。
続いて型検査を行い、エラーごとにアプリケーション、サーバー、共有コードのどの文脈に属するかを切り分けます。 - ビルドと主要な利用経路をテストする
開発サーバーが起動するだけでは移行完了とは判断できません。
本番用ビルド、直接URLを開いた場合の表示、ページ遷移、フォーム、認証、API通信、メタタグを確認します。 - 段階的に公開する
可能であれば検証環境で実運用に近いテストを行い、監視項目と切り戻し手順を決めてから本番へ反映します。
公開後はサーバーログ、ブラウザーのエラー、APIの失敗率を確認し、移行前との差を追います。
公開前の確認リスト
- 主要なURLと動的ルートを直接開いても表示できる
- サーバーが返すHTMLとブラウザー表示の間にハイドレーションエラーがない
- 同じデータを不要に複数回取得していない
- ローディング、空データ、通信失敗の表示が崩れていない
- ページタイトル、メタディスクリプション、canonical URLが意図どおりである
- プラグインとミドルウェアが想定した順序と環境で動く
- 利用中のNuxtモジュールに未対応の警告がない
- キーボード操作、フォーカス表示、フォームラベルなど既存のアクセシビリティを維持している
- 本番用ビルドとデプロイ手順を再現できる
- 問題が起きた場合の切り戻し方法が決まっている
移行で迷ったときの優先順位
Nuxt 4への移行は、ディレクトリだけを移動する作業ではありません。
依存関係、データ取得、型、表示結果を順番に検証し、どの変更が不具合を生んだか追える単位で進めます。
既存構成を維持できる後方互換性とCodemodは、移行を急ぐためではなく、変更を小さく分けるために使えます。
プロジェクト固有の設定は公式アップグレードガイドと照合し、ビルドと主要な利用経路のテストが通った時点で公開を判断してください。
公式資料
この記事に関連する株式会社greedenの取り組み
Nuxt 4への移行では、依存モジュール、型、データ取得、テストを段階ごとに確認する必要があります。株式会社greedenは、Webシステムの要件定義から実装、テスト、リリース後の保守まで支援し、既存システムの移行にも対応しています。