Nuxt3からNuxt4へのアップグレードガイド：@nuxt/content対応と移行戦略

/
├── app
│   └── spa-loading-template.html
├── app.vue
├── assets/
├── changelog.config.json
├── components/
├── composables/
├── config/
├── content/
├── error.vue
├── eslint.config.mjs
├── layouts/
├── logic/
├── mdc.config.ts
├── middleware/
├── nuxt.config.ts
├── package.json
├── pages/
├── plugins/
├── pnpm-lock.yaml
├── public/
├── scripts/
├── server/
    ├── api/
    ├── plugins/
    └── routes/
├── templates/
├── tsconfig.json
├── types/
├── uno.config.ts
├── utils/
└── vercel.json

Nuxt4のディレクトリ例json

/
├── app/
│   ├── app.vue
│   ├── assets/
│   ├── components/
│   ├── composables/
│   ├── error.vue
│   ├── middleware/
│   ├── layouts/
│   ├── pages/
│   ├── plugins/
│   ├── spa-loading-template.html
│   └── utils/
├── changelog.config.json
├── config/
├── content/
├── eslint.config.mjs
├── logic/
├── mdc.config.ts
├── nuxt.config.ts
├── package.json
├── pnpm-lock.yaml
├── layers/
├── modules/
├── public/
├── scripts/
├── server/
    ├── api/
    ├── middleware/
    ├── plugins/
    ├── routes/
    └── utils/
├── templates/
├── tsconfig.json
├── types/
├── uno.config.ts
└── vercel.json

npx codemod@latest nuxt/4/migration-recipe というNuxt4レディのディレクトリ構造にしてくれるスクリプトが紹介されています。一応上記に準じて移動はしてくれますが、空のディレクトリが元の位置に残ったままになってしまうようです。

@nuxt/contentは version2.13.0からNuxt4レディとなりました。つまり、元のまま<rootDir>直下に置いたままで機能するようになりました。理由があって、これ以前のバージョンを使われる方は、<srcDir>に移動すれば問題なく機能します。

共有プリレンダリングデータ

変更点：useAsyncDataとuseFetchの呼び出し結果を異なるページ間で共有する機能が有効化されます。

理由： プリレンダリング時のパフォーマンスを大幅に向上させるため。

コード例：

Nuxt3の書き方ts

// 各ページで個別にデータをフェッチ
const { data } = await useFetch('/api/menu')

Nuxt4の書き方ts

// データは自動的に共有される
const { data } = await useFetch('/api/menu', {
  key: 'menu-data' // キーを指定してデータを識別
})

中程度の変更

コンポーネント名の正規化

変更点： Vueが生成するコンポーネント名がNuxtのパターンに合わせて正規化されます。

理由： コンポーネント名の一貫性を確保し、自動インポートとの整合性を高めるため。

コード例：

Nuxt3の場合vue

<!-- components/SomeFolder/MyComponent.vue -->
<script>
export default {
  name: 'MyComponent'
}
</script>

Nuxt4の場合vue

<!-- components/SomeFolder/MyComponent.vue -->
<script>
export default {
  name: 'SomeFolderMyComponent'
}
</script>

軽微な変更

useAsyncDataとuseFetchのデフォルト値

変更点：useAsyncDataとuseFetchから返されるdataとerrorオブジェクトのデフォルト値がundefinedになります。

理由： 一貫性を高め、clearNuxtDataとの挙動を統一するため。

コード例：

Nuxt3の場合ts

const { data, error } = await useAsyncData(...)
// data.value === null
// error.value === null

Nuxt4の場合ts

const { data, error } = await useAsyncData(...)
// data.value === undefined
// error.value === undefined

Experimental Featuresを削除

変更点： Nuxt 4では、以下の4つの実験的な機能が設定できなくなりました。

experimental.treeshakeClientOnlyがtrueになります（v3.0以降のデフォルト）。
experimental.configSchema が true になります（v3.3 以降のデフォルト）。
experimental.polyfillVueUseHeadがfalseになります（デフォルトはv3.4以降）。
experimental.respectNoSSRHeaderがfalseになります（v3.4以降のデフォルト）。
vite.devBundlerは設定できなくなりました。

理由： これらのオプションを設定可能なままにしておく必要があると考える理由はありません。

基本的に実験的な機能はデフォルトのままにしておいて良いようです。＊ただ、Nuxtaionの場合は、 sharedPrerenderData: false にしてあります。

4. 移行戦略

プロジェクト構造の更新：
- app/ ディレクトリを作成し、既存のアセット、コンポーネント、レイアウトなどを移動する。
- server/ ディレクトリをルートに移動する。
nuxt.config.ts ファイルの修正：
- 新しい設定オプションを追加し、必要に応じて古い設定を更新する。
新しいルーティングシステムへの適応：
- ページコンポーネントとルーティング関連のコードを確認し、必要に応じて更新する。
APIエンドポイントとサーバーサイドコードの更新：
- server/ ディレクトリ内のコードを新しい構造に合わせて調整する。
コンポーネントとcomposablesのリファクタリング：
- 新しい命名規則に合わせてコンポーネント名を更新する。
- useAsyncDataとuseFetchの使用箇所を確認し、新しいデフォルト値に対応する。

5. ベストプラクティスとヒント

段階的な移行を行う：Nuxt 最新版でcompatibilityVersion: 4を設定して、徐々に新機能を有効化する。
TypeScriptの型チェックを厳格にする：tsconfig.jsonのstrictオプションを有効にする。
新しいディレクトリ構造を活用して、コードの整理と分離を行う。
共有プリレンダリングデータ機能を活用し、パフォーマンスを最適化する。

6. パフォーマンスの改善

Nuxt4では、以下のパフォーマンス改善が期待できます：

Nitroエンジンの強化による高速なサーバーサイドレンダリングと静的サイト生成
共有プリレンダリングデータによるビルド時間の短縮
最適化されたファイル構造によるアプリケーション起動時間の改善

これらの改善を活用するには、新しいディレクトリ構造を採用し、useAsyncDataとuseFetchを効果的に使用することが重要です。

7. まとめ

Nuxt4への移行は、いくつかの重要な変更を伴いますが、パフォーマンスと開発者体験の大幅な向上をもたらします。主なポイントは以下の通りです：

新しいディレクトリ構造の採用
共有プリレンダリングデータ機能の活用
コンポーネント名の正規化への対応
useAsyncDataとuseFetchの新しいデフォルト値への適応

Nuxt 最新のバージョンを使用して、徐々にNuxt4の機能を取り入れることで、スムーズな移行が可能です。TypeScriptのサポート強化やNitroエンジンの統合強化など、Nuxt4の新機能を活用することで、より効率的で高性能なアプリケーション開発が可能になります。

Nuxt4の正式リリースに向けて、これらの変更点を理解し、プロジェクトの準備を進めることをお勧めします。