---
title: "Nuxt3からNuxt4へのアップグレードガイド：@nuxt/content対応と移行戦略"
description: "Nuxt3からNuxt4へのアップグレード方法を解説。新機能、破壊的変更、ファイル構造の変更、ベストプラクティスなど、スムーズな移行のための完全ガイド。"
canonical_url: "https://nuxtation.vercel.app/blog/nuxt3-to-nuxt4-upgrade-guide-with-nuxt-content"
---
# Nuxt3からNuxt4へのアップグレードガイド：@nuxt/content対応と移行戦略

> Nuxt3からNuxt4へのアップグレード方法を解説。新機能、破壊的変更、ファイル構造の変更、ベストプラクティスなど、スムーズな移行のための完全ガイド。

## 1. はじめに

Nuxt4の開発は現在進行中であり、正式なリリース日はまだ発表されていません。しかし、Nuxt 3.12以降のバージョンでは、Nuxt4の多くの破壊的変更を先行して体験できるようになっています。これにより、開発者はNuxt4への移行を徐々に進めることができます。

Nuxt2やNuxt-BridgeからNuxt3に移行するときに苦労された方はちょっと拍子抜けしてしまうぐらい簡単です。私が解説するまでもないとは思いますが、書いてしまいます。

参照；[https://nuxt.com/docs/getting-started/upgrade](https://nuxt.com/docs/getting-started/upgrade)

### 2. 主な変更点と新機能

#### a. ファイル構造の変更

Nuxt4では、新しいデフォルトのディレクトリ構造が導入されます。主な変更点は以下の通りです：

- **app/** ディレクトリが新しいデフォルトの**srcDir**となります。
- **server/** ディレクトリは **<rootDir>/server**に配置されます。
- **layers/**、**modules/**、**public/** ディレクトリは **<rootDir>** からの相対パスで解決されます。

#### b. Nitroエンジンの統合強化

Nuxt4では、Nitroエンジンとの統合がさらに強化されます。これにより、サーバーサイドレンダリングと静的サイト生成のパフォーマンスが向上します。

#### c. 新しいルーティングシステム

ルーティングシステムが刷新され、サーバーサイドとクライアントサイドで共有されるユニバーサルなルーティングが導入されます。

#### d. モジュールシステムの進化

Nuxt4では、モジュールシステムがさらに進化し、より柔軟性が高くなります。

#### e. TypeScriptのサポート強化

TypeScriptのサポートが強化され、開発中の型安全性がより高まります。

### 3. 破壊的変更

#### 重要な変更

##### ファイル構造の変更

**変更点：**
Nuxt4では、新しいデフォルトのディレクトリ構造が導入されます。

**理由：**

1. パフォーマンス向上：**.git/** や**node_modules/** フォルダのスキャンによる起動遅延を防ぐ。
2. IDE型安全性の向上：**server/** とアプリの他の部分を分離することで、コンテキストの違いを明確にする。

**コード例：**
Nuxtationの実例

<directory-comparison>

```text [Nuxt 3のディレクトリ例]
/
├── 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
```

```text [Nuxt 4のディレクトリ例]
/
├── app/
│   ├── app.vue
│   ├── assets/
│   ├── components/
│   ├── composables/
│   ├── error.vue
│   ├── layouts/
│   ├── middleware/
│   ├── pages/
│   ├── plugins/
│   ├── spa-loading-template.html
│   └── utils/
├── changelog.config.json
├── config/
├── content/
├── eslint.config.mjs
├── layers/
├── logic/
├── mdc.config.ts
├── modules/
├── nuxt.config.ts
├── package.json
├── pnpm-lock.yaml
├── public/
├── scripts/
├── server/
│   ├── api/
│   ├── middleware/
│   ├── plugins/
│   ├── routes/
│   └── utils/
├── templates/
├── tsconfig.json
├── types/
├── uno.config.ts
└── vercel.json
```

</directory-comparison>

<alert type="info">

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

</alert>

<alert type="warning">

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

</alert>

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

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

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

**コード例：**

```ts [Nuxt3の書き方]
// 各ページで個別にデータをフェッチ
const { data } = await useFetch('/api/menu')
```

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

#### 中程度の変更

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

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

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

**コード例：**

```vue [Nuxt3の場合]
<!-- components/SomeFolder/MyComponent.vue -->
<script>
export default {
  name: 'MyComponent'
}
</script>
```

```vue [Nuxt4の場合]
<!-- components/SomeFolder/MyComponent.vue -->
<script>
export default {
  name: 'SomeFolderMyComponent'
}
</script>
```

#### 軽微な変更

##### useAsyncDataとuseFetchのデフォルト値

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

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

**コード例：**

```ts [Nuxt3の場合]
const { data, error } = await useAsyncData(...)
// data.value === null
// error.value === null
```

```ts [Nuxt4の場合]
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以降のデフォルト）。<br />

vite.devBundlerは設定できなくなりました。

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

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

### 4. 移行戦略

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

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

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

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

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

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

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

### 7. まとめ

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

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

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

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


## Sitemap

See the full [sitemap](https://nuxtation.vercel.app/sitemap.md) for all pages.