インストール

Nuxt 3 を使いはじめるのは簡単です。

オンラインで試す

Nuxt 3 はオンラインの sandbox などを使用してブラウザから使いはじめることができます。

新しいプロジェクト

ターミナルを開くか、Visual Studio Code から 統合ターミナル を開き、次のコマンドを使用して新しいスタータープロジェクトを作成します:

npx nuxi init nuxt3-app

or

yarn dlx nuxi init nuxt3-app

or

pnpm dlx nuxi init nuxt3-app

visual studio code で nuxt3-app フォルダを開いてください:

code nuxt3-app

依存関係をインストールします:

yarn install 

or

npm install 

or

pnpm install --shamefully-hoist

開発サーバー

これで、yarn dev を使って開発モードで nuxt アプリを起動できるようになります:

yarn dev -o

or

npm run dev -- -o

or

pnpm run dev -- -o

次のステップ

これで Nuxt 3 プロジェクトが作成できたので、アプリケーションの構築を開始する準備ができました。

• コンセプト について学ぶ
• 使用方法 について詳しく知る

Bridge

既存の Nuxt 2 のプロジェクトで Nuxt 3 の機能を体験する。

Bridge は、Nuxt モジュールをインストールして有効にするだけで、Nuxt 3 の新機能の多くを体験できる前方互換性のあるレイヤーです。

Nuxt Bridge を使用することで、プロジェクトを Nuxt 3 に（ほぼ）対応させることができ、大幅な書き換えや変更を加えるリスクなしに最高の開発者体験を得ることができます。

Nuxt 2 をアップグレード

開発サーバー（nuxt dev）が起動していないことを確認し、package lock ファイル（package-lock.json と yarn.lock）を削除し、最新の nuxt-edge をインストールしてください:

- "nuxt": "^2.15.0"
+ "nuxt-edge": "latest"

そのあと、依存関係を再インストールしてください:

yarn install

or

npm install

Nuxt Bridge をインストール

開発依存として @nuxt/bridge-edge をインストールします:

yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge

or

npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge

scripts をアップデート

また、Nuxt が Nitro サーバーをビルド出力として生成するようになったことを反映して、package.json 内の scripts を更新する必要があります。

Nuxi

Nuxt 3 では、新しい Nuxt CLI コマンドである nuxi が導入されました。Nuxt Bridge のより良いサポートを利用するために、以下のように scripts を更新してください:

{
  "scripts": {
-   "dev": "nuxt",
+   "dev": "nuxi dev",
-   "build": "nuxt build",
+   "build": "nuxi build",
-   "start": "nuxt start",
+   "start": "nuxi preview"
  }
}

静的ターゲット

nuxt.config で target: 'static' を設定している場合は、ビルド scripts を nuxi generate に更新することを確認する必要があります。

{
  "scripts": {
    "build": "nuxi generate"
  }
}

サーバーターゲット

それ以外の場合は、nuxi build コマンドを使用します。

{
  "scripts": {
    "build": "nuxi build",
    "start": "nuxi preview"
  }
}

nuxt.config をアップデート

設定ファイルでは、module.exports、require、require.resolve などの CommonJS の構文を使わないように注意してください。

代わりに、static import、dynamic import()、export default を使用することができます。また、nuxt.config.ts に名前を変更することで TypeScript を使用することも可能であり、推奨されています。

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  // 設定
})

tsconfig.json をアップデート

TypeScript を使用している場合、tsconfig.json を編集することで、自動生成された Nuxt の型を利用することができます。

{
+ "extends": "./.nuxt/tsconfig.json",
  "compilerOptions": {
    ...
  }
}

Composition API に移行

以前、@vue/composition-api や @nuxtjs/composition-api を使用していた場合は、composition api 移行ガイド をお読みください。

CommonJS から ESM に移行

Nuxt 3 は TypeScript と ECMAScript Modules をネイティブでサポートしています。詳細とアップグレードについては、Native ES Modules をご覧ください。

互換性のないモジュールや旧式のモジュールを削除

• nuxt/content を削除（1.x）してください。nuxt 3 用の書き換えが予定されています (2.x)
• nuxt-vite を削除してください。Bridge で同機能を実現します
• nuxt/typescript-build を削除してください。Bridge で同機能を実現します
• nuxt/typescript-runtime と nuxt-ts を削除してください。Nuxt 2 はランタイムサポートを内蔵しています
• nuxt/nitro を削除してください。Bridge は同じ機能を持っています
• vue/composition-api を依存関係から削除してください (移行ガイド )
• nuxtjs/composition-api を依存関係から削除してください(および nuxt.config のモジュールから) (移行ガイド)

ビルドした Nitro フォルダを git から除外

.gitignore ファイルに .output フォルダを追加します。

すべてがうまくいくことを確認する

✅ nuxi dev と nuxi build（または nuxi generate）で試してみて、すべてがうまくいくかどうか確認してください。

🐛 何か問題がありますか？ issue を作成してお知らせください。また、その間に bridge を無効にすることも簡単にできます。

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: false // bridge 統合の一時的な無効化
})

新しいプラグインフォーマット(オプション)

Nuxt 2 とは形式が若干異なる Nuxt 3 プラグイン API に移行することができるようになりました。

プラグインは 1 つの引数（nuxtApp）だけを取るようになりました。詳しくはドキュメントをご覧ください。

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.provide('injected', () => 'my injected function')
  // `nuxtApp.$injected` で利用可能になりました。
})

新しい useMeta(オプション)

Nuxt Bridge は新しい Nuxt 3 meta API を提供し、新しい useMeta composable でアクセスすることができます｡

<script setup>
import { useMeta } from '#app'
useMeta({
  title: 'My Nuxt App',
})
</script>

また、nuxt.config でこの機能を明示的に有効にする必要があります:

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    meta: true
  }
})

この useMeta composable は、(vue-meta ではなく) @vueuse/head を内部に使って <head> を操作しています。したがって、Nuxt 2 のネイティブな head() プロパティと useMeta の両方を使用することは、競合する可能性があるので、推奨されません。

この composable の使い方の詳細は、ドキュメントを参照してください。

機能フラグ

オプションで bridge からいくつかの機能を無効にしたり、より安定性の低い機能をオプトインすることができます。通常の場合、デフォルトのままにしておくのが一番です！

最新のデフォルトは、bridge/src/module.ts で確認できます。

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {

    // -- オプトインの特徴 --

    // Webpack 4 の代わりに Vite をバンドラーとして使用する
    // vite: true,

    // Nuxt 3 互換の useMeta を使用可能にする。
    // meta: true,

    // -- デフォルトの特徴 --

    // Nitro の代わりにレガシーサーバーを使用する
    // nitro: false,

    // Nuxt 3 互換の `nuxtApp` インターフェースを無効にする
    // app: false,

    // Composition API サポートを無効にする
    // capi: false,

    // ... あるいは、従来の Composition API のサポートを無効にする
    // capi: {
    //   legacy: false
    // },

    // モジュールをトランスパイルしない
    // transpile: false,

    // <script setup> サポートを無効にする
    // scriptSetup: false,

    // composables の自動インポートを無効にする
    // autoImports: false,

    // モジュールの非互換性についての警告を表示しない
    // constraints: false
  },

  vite: {
    // Vite 用の設定
  }
})

コマンド

Nuxi は Nuxt 3 の新しい CLI 体験です

Nuxt 3 には、開発用サーバーを起動するコマンドと、本番用アセットを作成するコマンドの大きく 2 つがあります。

Nitro サーバーを導入したことにより、Nuxt 3 は開発依存となったため、package.json に 2 つのコマンドを追加するだけでいいです:

"scripts": {
  "dev": "nuxi dev",
  "build": "nuxi build",
}

そして、npm run <command> または yarn <command> を使って各コマンドを実行することができます。

開発サーバー

http://localhost:3000 を開いて､ホットモジュール交換による開発モードの Nuxt を起動する:

yarn dev

or

npm run dev

HTTPS https://localhost:3000 (自己署名証明書)を使って開発モードで Nuxt を起動する:

yarn dev --https

or

npm run dev -- --https

実運用に向けたビルド

Nuxt アプリケーションを本番用にビルドするには、以下を実行します:

yarn build

or

npm run build

Nuxt は、アプリケーション、サーバー、および依存関係をすべて含む .output ディレクトリを作成し、デプロイする準備ができます。Nitro を使用して Nuxt アプリケーションをデプロイする場所と方法については、デプロイメント のセクションを参照してください。

CLI 用語集

移行

Nuxt 3 への移行ガイドです｡作業中です 🚧

Nuxt 2 から Nuxt 3 へ

現時点では、Nuxt 2 から Nuxt 3 への移行ガイドはありませんし、さらなる変更の可能性があるため、移行は推奨されません。できるだけスムーズに移行できるよう、安定した移行ガイドとツールの提供に取り組んでいます。代替ツールについては、Bridge をご確認ください。

Nuxt 2 から削除された機能、Nuxt 3 にまだ実装されていない機能、Nuxt 3（および Bridge）で新たに追加された機能があります。

Nuxt Bridge の要件以外で、Nuxt 3 における顕著な､または重要な変更点は以下のとおりです:

• ℹ️ Vue アプリのテンプレートを書き直しました
• ℹ️ Vue を 3.x にアップグレード
• ℹ️ 非同期データ取得のために <Suspense> を使用
• ℹ️ Webpack 5.x (vite を使用しない場合)
• ℹ️ コンポーネントの発見機能を書き直しました
• ℹ️ メインである app.vue コンポーネントを導入
• ℹ️ 新しい layouts システムを導入
• ℹ️ pages/ ディレクトリの規約を変更

下表は、全体的な機能比較のハイライトです。

モジュールの互換性

すべての Nuxt 2 モジュールは、bridge に移行する場合、またはすでにガイドラインに従っている場合は、Nuxt 3 と前方互換性があるはずです。

@nuxt/kit で作成されたすべての（今後の）モジュールは、Nuxt 3 / Bridge 専用の機能に依存していない限り、Nuxt 2 プロジェクトと後方互換性があるべきです（bridge を使用していない場合も）。

プラグイン互換性

ほとんどの Nuxt 2 プラグインは、私たちが導入する魔法の互換レイヤーを使って Nuxt 3 と前方互換性があるはずです。

Nuxt 3 のプラグインは Nuxt 2 との後方互換性がありません。

Vue との互換性

composition API やコンポーネントを使用するプラグインは、Vue 2 または Vue 3 に排他的に対応する必要があります。

vue-demi を使用することで、Nuxt 2 と 3 の両方に互換性があるはずです。

モジュールの移行

Nuxt 3 ユーザーがあなたのモジュールを追加すると、@nuxt/kit から互換性のあるモジュールコンテナレイヤーが自動的に導入されるので、あなたのコードが以下のガイドラインに従っている限り、そのまま動作し続けるはずです。

nuxt/bridge でテストする

@nuxt/bridge への移行は、Nuxt 3 をサポートするための最初で最も重要なステップです。

モジュール内にフィクスチャやサンプルがある場合、その設定に @nuxt/bridge パッケージを追加します (例を参照)。

CommonJS から ESM への移行

Nuxt 3 は TypeScript と ECMAScript Modules をネイティブにサポートしています。詳細とアップグレードについては、Native ES Modules を参照してください。

プラグインがデフォルトでエクスポートされるようにする

export default を持たない Nuxt プラグイン（グローバルな Vue プラグインなど）を導入する場合は、export default () => { } を末尾に追加することを確認してください。

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

export default () => { }

ランタイムモジュールを避ける

Nuxt 3 では、Nuxt はビルド時のみの依存関係になりました。これは、モジュールが Nuxt ランタイムにフックしようとすべきではないことを意味します。

モジュールのニーズは、（モジュールではなく）buildModules に追加されただけでも動作するはずです。例えば、

• Nuxt モジュール内で process.env を更新し、nuxt プラグインで読み込むことは避け、代わりに runtimeConfig を使用します。
• (*) vue-renderer:* のようなランタイムフックに依存した制作は避けましょう。
• (*) serverMiddleware をモジュール内部でインポートして追加することは避けてください。代わりに、ファイルパスを参照して追加することで、モジュールのコンテキストに依存しないようにします。

(*) nuxt dev の目的のみで、if (nuxt.options.dev) { } でガードされている場合は別です。

TypeScript を使用する（オプション）

必須ではありませんが、Nuxt のエコシステムのほとんどが TypeScript の利用にシフトしていますので、移行を検討されることを強くお勧めします。

Vue.js 開発

Nuxt は、フロントエンドフレームワークとして Vue を使用し、コンポーネントの自動インポートやファイルベースのルーティングなどの機能を追加しています。Nuxt 3 は、Vue の新しいメジャーリリースである Vue 3 を統合し、Nuxt ユーザーのための新しいパターンを可能にします。

Vue.js

Nuxtを使用するために Vue の深い知識は必要ありませんが、ドキュメントを読み、vuejs.org にあるいくつかの例を見てみることをお勧めします

Nuxt は、フロントエンドフレームワークとして常に Vue を使用しています。私たちが Nuxt を Vue の上に構築することを選択したのは、以下のような理由からです。

• Vue のリアクティビティ（反応的な）・モデルは、データの変化が自動的にインターフェースの変化を引き起こすというものです。
• コンポーネントベースのテンプレートは、HTML をウェブの共通言語として維持しながら、直感的なパターンを可能にし、インターフェイスの一貫性を保ちつつ、パワフルなものにします。
• 小規模なプロジェクトから大規模な web アプリケーションまで、Vue はスケールアップしても優れたパフォーマンスを発揮し続け、アプリケーションがユーザーに価値を提供し続けることを保証します。

Vue と Nuxt

単一ファイルコンポーネント

Vue の単一ファイルコンポーネント（SFC、または *.vue ファイル）は、Vue コンポーネントのマークアップ（<template>）、ロジック（<script>）、スタイル（<style>）をカプセル化したものです。Nuxt は、シームレスな開発者体験を提供する Hot Module Replacement（画面の再描画無しに JS の変更をブラウザに適用してくれるもの） により、SFC のためのゼロ設定体験を提供します。

コンポーネントの自動インポート

Nuxt プロジェクトの components/ ディレクトリに作成されたすべての Vue コンポーネントは、インポートしなくてもあなたのプロジェクトで利用できるようになります。コンポーネントがどこにも使用されていない場合、プロダクションのコードには含まれません。

Vue Router

ほとんどのアプリケーションでは、複数のページと、それらの間を移動する方法が必要です。これをルーティングと呼びます。Nuxt は、pages/ ディレクトリと命名規則を使用して、公式の Vue Router ライブラリ を使用してファイルにマッピングされたルートを直接作成します。

例

app.vue ファイルは、ブラウザのウィンドウに表示されるページを表すエントリーポイントです。

コンポーネントの <template> 内では、components/ ディレクトリに作成された<Welcome> コンポーネントをインポートすることなく使用しています。

<template> の内容をカスタムのウェルカムメッセージに置き換えてみてください。右のブラウザウィンドウは、リロードせずに自動的に変更内容をレンダリングします。

Nuxt 2 または Vue 2 の以前のユーザーであれば、Vue 2 と Vue 3 の違いや、Nuxt がこれらの進化をどのように統合しているかを知るために読み続けてください。

そうでない場合は、次の章で Nuxt のもう一つの重要な機能を発見してください: レンダリングモード

Nuxt 2 / Vue 2 とのちがい

Nuxt 3 は、Vue 3 をベースにしています。新しい Vue のメジャーバージョンでは、Nuxt が活用できるいくつかの変更点が導入されています:

• パフォーマンスの向上
• Composition API
• TypeScript サポート

より高速なレンダリング

Vue Virtual DOM （VDOM）はゼロから書き直され、より良いレンダリングパフォーマンスを可能にしました。さらに、コンパイルされた単一ファイルコンポーネントを扱う場合、Vue コンパイラは、静的マークアップと動的マークアップを分離することによって、ビルド時にコンポーネントをさらに最適化することができます。

その結果、最初のレンダリング（コンポーネント作成）と更新が高速化され、メモリ使用量も少なくなります。Nuxt 3 では、サーバーサイドレンダリングの高速化も可能になりました。

より小さいバンドル

Vue 3 と Nuxt 3 では、バンドルサイズの縮小に重点が置かれています。バージョン 3 では、テンプレートディレクティブや組み込みコンポーネントなど、Vue の機能のほとんどが Tree shaking（実行されないコードを削除すること）が可能になっています。それらを使用しない場合、プロダクションバンドルにはそれらが含まれません。

こうすることで、最小限のVue 3アプリケーションを gzip で 12kb に圧縮することができます。

Composition API

Vue 2 でコンポーネントにデータやロジックを提供する唯一の方法は Options API で、data や methods のようなあらかじめ定義されたプロパティをテンプレートに返すことができるようになりました:

<script>
export default {
  data() {
    return {
      count: 0
    }
  },
  methods: {
    increment(){
      this.count++
    }
  }
}
</script>

Vue 3 で導入された Composition API は、Options API に代わるものではありませんが、アプリケーション全体でより良いロジックの再利用を可能にし、複雑なコンポーネントで懸念事項によってコードをグループ化する、より自然な方法を提供します。

<script> 定義の setup キーワードを使用して、上記のコンポーネントを Composition API と Nuxt 3 の自動インポートされた Reactivity API で書き直したものがこちらです:

<script setup>
  const count = ref(0)
  const increment = () => count.value++
</script>

Nuxt 3 の目標は、Composition API を中心とした優れた開発者体験を提供することです。

• Vue と Nuxt 3 内蔵の composables から自動インポートされた Reactivity 関数 を使用します。
• composables/ ディレクトリに自動インポートされた再利用可能な独自の関数を記述します。

TypeScript サポート

Vue 3 と Nuxt 3 はどちらも Typescript で書かれています。完全に型付けされたコードベースはミスを防ぎ、API の使い方を文書化します。これは、Typescript を活用するためにアプリケーションを書かなければならないということではありません。Nuxt 3 では、ファイル名を .js から .ts に変更したり、コンポーネント内に <script lang="ts"> を追加することで、TypeScript を使用することができます。

レンダリングモード

ブラウザとサーバーは、Javascript のコードを解釈して、Vue.js コンポーネントを HTML 要素にレンダリングすることができます。このステップをレンダリングと呼びます。Nuxt はクライアントサイドとユニバーサルレンダリングの両方をサポートしています。この 2 つのアプローチには長所と短所があり、このセクションで説明します。

クライアントサイドのみのレンダリング

従来の Vue.js アプリケーションは、すぐにブラウザ（または クライアント）上でレンダリングされます。そして、ブラウザが現在のインターフェイスを作成するための命令を含むすべての Javascript コードをダウンロードして解析した後、Vue.js は HTML 要素を生成します。

この手法により、複雑でダイナミックな UI を構築し、スムーズなページ遷移を実現することができますが、異なる長所と短所があります。

長所

• 開発スピード: 完全にクライアントサイドで作業する場合、window オブジェクトのようなブラウザ専用の API を使用するなど、コードのサーバー互換性を気にする必要がありません。
• 低コスト: サーバーを稼働させる場合、Javascript をサポートするプラットフォームで稼働させる必要があるため、インフラストラクチャのコストがかかります。クライアント専用のアプリケーションは、HTML、CSS、Javascript のファイルだけで、どんな静的なサーバーでもホストすることができます。
• オフライン: コードはすべてブラウザ上で実行されるため、インターネットが利用できない状態でも、きれいに動作し続けることができます。

短所

• パフォーマンス: ユーザーは、ブラウザが JavaScript ファイルをダウンロードし、解析し、実行するのを待つ必要があります。ダウンロードはネットワークに依存し、解析と実行はユーザーのデバイスに依存するため、時間がかかり、ユーザーエクスペリエンスに影響を与える可能性があります。
• 検索エンジン最適化: クライアントサイドレンダリングで配信されるコンテンツのインデックス作成と更新には、すでに構築された HTML ドキュメントよりも多くの時間がかかります。これは、先ほど説明したパフォーマンスの欠点と関係があります。検索エンジンのクローラーは、ページをインデックスするための最初の試みで、インターフェイスが完全にレンダリングされるのを待たないからです。したがって、純粋なクライアントサイド・レンダリングでは、検索結果ページでのコンテンツの表示と更新に時間がかかります。

事例

クライアントサイドレンダリングは、インデックス作成の必要がない、または同じユーザーを頻繁に使用する、高度にインタラクティブな ウェブアプリケーション に適した方法です。ブラウザのキャッシュを活用して、SaaS、バックオフィスアプリケーション、オンラインゲーム など、次回以降の訪問時にダウンロードフェーズをスキップすることができます。

ユニバーサルレンダリング

ユニバーサル（クライアントサイド＋サーバーサイド）レンダリングを有効にしてブラウザが URL をリクエストすると、完全にレンダリングされた HTML ページがブラウザに返されます。ページが事前に生成されてキャッシュされている場合も、オンザフライでレンダリングされる場合も、Nuxt はサーバー環境で Javascript（Vue.js）のコードを実行し、HTML ドキュメントを生成していることに変わりはありません。ユーザーは、クライアントサイドレンダリングとは逆に、我々のアプリケーションのコンテンツをすぐに手に入れることができます。このステップは、PHP や Ruby のアプリケーションが行う従来の サーバーサイドレンダリング に似ています。

動的なインターフェースやページ遷移など、クライアントサイドレンダリング方式の利点を失わないために、サーバー上で実行される JavaScript コードは、HTML ドキュメントがダウンロードされるとバックグラウンドでクライアントによってロードされます。HTML 文書がブラウザによって再び解釈されると（ユニバーサルレンダリング のため）、Vue.js が文書を制御し、インタラクティブ性を実現します。

静的なページをブラウザ上でインタラクティブにすることを "ハイドレーション "と呼びます。

ユニバーサルレンダリングにより、Nuxt アプリケーションはクライアントサイドレンダリングの利点を生かしながら、ページの読み込み時間を短縮することができる。さらに、コンテンツがすでに HTML ドキュメント内に存在するため、クローラーはオーバーヘッドなしにインデックスを作成することができる。

長所

• パフォーマンス: ブラウザは、Javascript で生成されたものよりも静的なコンテンツをより速く表示できるため、ユーザーはページのコンテンツにすぐにアクセスすることができます。同時に、Nuxt はハイドレーションプロセスが発生しても、web アプリケーションのインタラクティブ性を維持します。
• 検索エンジン最適化: ユニバーサルレンダリングは、ページの HTML コンテンツ全体をクラシックなサーバーアプリケーションとしてブラウザに配信します。ウェブクローラーは、ページのコンテンツを直接インデックスすることができます。そのため、ユニバーサルレンダリングは、迅速にインデックスしたいあらゆるコンテンツに最適な選択肢となります。

短所

• 開発の制約: サーバーとブラウザーの環境は同じ API を提供していないため、両側でシームレスに動作するコードを書くのは難しい場合があります。幸いなことに、Nuxt はガイドラインと特定の変数を提供し、コードの一部がどこで実行されるかを決定するのに役立ちます。
• 高コスト: オンザフライでページをレンダリングするためには、サーバーを稼働させる必要があります。これには、従来のサーバーと同様に毎月のコストがかかります。しかし、ユニバーサルレンダリングでは、クライアントサイドのナビゲーションをブラウザが引き継ぐため、サーバーの呼び出しは大幅に削減されます。

事例

ユニバーサルレンダリングは非常に汎用性が高く、ほとんどのユースケースに対応できます。特に、ブログ、マーケティングウェブサイト、ポートフォリオ、Eコマース、マーケットプレイス など、コンテンツ重視のウェブサイトに適しています。

概要

クライアントサイドとユニバーサルレンダリングは、ブラウザでインターフェイスを表示するための異なる戦略です。

デフォルトでは、Nuxt はより良いユーザー体験とパフォーマンスを提供し、検索エンジンのインデックスを最適化するために ユニバーサルレンダリング を使用しますが、1 行の設定 でレンダリングモードを切り替えることができます。

Nuxt 3 で登場

多くの場合、Nuxt 2 で実行されるユニバーサルレンダリングは、ユーザーと開発者に良い経験を提供します。しかし、Nuxt 3 では、ハイブリッドレンダリングとエッジサイドレンダリングを導入することにより、ユニバーサルレンダリングをさらに進化させます。

ハイブリッドレンダリング

ハイブリッドレンダリングは、ルートごとに異なるキャッシュルールを許可し、与えられた URL の新しいリクエストにサーバーがどのように応答すべきかを決定します。

現時点では、Nuxt アプリケーションのすべてのページ（または ルート）は、クライアントサイドまたはユニバーサルという同じレンダリングモードを使用する必要があります。しかし、さまざまなケースで、いくつかのページは構築時に生成され、他のページはクライアントサイドでレンダリングされる必要があります。たとえば、管理セクションを持つコンテンツウェブサイトを考えてみましょう。すべてのコンテンツページは主に静的で一度だけ生成されるべきですが、管理セクションは登録が必要で、より動的なアプリケーションのように動作します。

実装を議論し、コミュニティのフィードバックを収集するオープン RFC を読む

CDN エッジワーカーでのレンダリング

従来、サーバーサイドやユニバーサルレンダリングは、Node.js でなければできませんでした。Nuxt 3 は、CDN エッジワーカーのコードを直接レンダリングすることで、レイテンシー（データ通信の待ち時間）とコストを削減し、さらにレベルアップします。

Nitro は、Nuxt 3 を支える新しい サーバーエンジン です。Node.js、Deno、Workers などをクロスプラットフォームでサポートします。Nitro のデザインはプラットフォームにとらわれず、Nuxt アプリケーションをユーザーにより近いエッジでレンダリングし、レプリケーションとさらなる最適化を可能にします。

Nuxt 3 アプリケーションをサーバーレスプロバイダーにデプロイする

自動インポート

Nuxt は、ヘルパー関数、Composables、Vue API を明示的にインポートしなくても、アプリケーション全体で使用できるように自動インポートします。ディレクトリ構造に基づいて、すべての Nuxt アプリケーションは、独自のコンポーネント、composables、プラグインのために自動インポートを使用することもできます。コンポーネント、composables、プラグインは、これらの関数を使用することができます。

古典的なグローバル宣言とは異なり、Nuxt は型付けと IDE の補完とヒントを保持し、プロダクションコードで実際に使用されるものだけを含めます。

Nuxt 自動インポート

Nuxt は、データの取得、アプリのコンテキスト や ランタイム設定 へのアクセス、状態 の管理、コンポーネントやプラグインの定義を行う関数やコンパイラを自動でインポートします。

<script setup>
  /* useAsyncData() と $fetch() は 自動インポートされます */
  const { data, refresh, pending } = await useAsyncData('/api/hello', () => $fetch('/api/hello'))
</script>

Vue 自動インポート

Vue 3 は、ref や computed といった Reactivity API や、Nuxt が自動でインポートするライフサイクルフックやヘルパーを公開しています。

<script setup>
  /* ref() and computed() are auto-imported */
  const count = ref(1)
  const double = computed(() => count.value * 2)
</script>

ディレクトリベースの自動インポート

Nuxt は定義されたディレクトリに作成されたファイルを直接自動インポートします。

• Vue compoents のための components/
• Vue composables のための composables/

明示的なインポート

Nuxt の自動インポートはすべて #imports というエイリアスで公開されており、必要に応じてこれを使用してインポートを明示することができます:

<script setup>
  import { ref, computed } from '#imports'

  const count = ref(1)
  const double = computed(() => count.value * 2)
</script>

サーバーエンジン

Nuxt 3 は、"Nitro（ナイトロ）" と呼ばれる新しいサーバーエンジンを搭載しています。

このエンジンには多くの利点があります。

• ✅ Node.js、ブラウザ、サービスワーカーなどのクロスプラットフォームのサポート
• ✅ サーバーレスを即座にサポート
• ✅ API ルートのサポート
• ✅ 自動的なコード分割と非同期ロードされたチャンク
• ✅ 静的サイト＋サーバーレスサイトのハイブリッドモード
• ✅ ホットモジュールリローディング機能付き開発サーバー

API レイヤー

サーバーの API のエンドポイントとミドルウェアは、内部で h3 を使用している Nitro によって追加されます。

以下のような主要な機能があります:

• ハンドラは、自動的に処理される JSON レスポンスに対して、オブジェクト/配列を直接返すことができる
• ハンドラは待ち受けとなるプロミスを返すことができる（res.end()、next() もサポートされている）
• ボディパース、クッキー処理、リダイレクト、ヘッダーなどのヘルパー関数

詳しくは h3 ドキュメント をご覧ください。

API を直接呼び出す

Nitro では、グローバルに利用可能な $fetch ヘルパーを使用して、ルートを「直接」呼び出すことができます。これは、ブラウザ上で実行された場合はサーバーへの API 呼び出しを行いますが、サーバー上で実行された場合は単に関連する関数を呼び出すので、追加の API 呼び出しを節約することができます 。

$fetch API は、ohmyfetch を使用しており、主な機能は以下の通りです。

• JSON レスポンスの自動パース（必要に応じて生のレスポンスにアクセス可能）
• リクエストボディとパラメータは自動的に処理され、正しい Content-Type ヘッダーが追加されます。

$fetch 機能の詳細については、ohmyfetch を参照してください。

型付き API ルート

API ルート（またはミドルウェア）を使用する場合、res.end() を使用してレスポンスを送信するのではなく、値を返す限り、Nitro はこれらのルートに対する型付けを生成します。

これらの型には、$fetch() や useFetch() を使用する際にアクセスすることができます。

スタンドアローン（単独で動作しているシステム）サーバー

Nitro は node_modules とは独立したスタンドアローンサーバー dist を生成します。

Nuxt 2 のサーバーはスタンドアローン（単独で動作しているシステム）ではなく、nuxt start の実行（nuxt-start や nuxt ディストリビューションを使用）やカスタムプログラムによる使用など、nuxt core の一部が関与する必要があり、壊れやすくサーバーレスやサービスワーカーの環境には向いていないものでした。

この dist は、nuxt build を実行すると、.output ディレクトリに生成されます。

この出力は、ランタイムコードの両方と組み合わされ、Nuxt サーバーをあらゆる環境（実験的なブラウザサービスワーカーを含みます！）で実行し、静的ファイルを提供する、JAMstack のための真のハイブリッドフレームワークとなっています。さらに、ネイティブストレージレイヤーが実装されており、マルチソース、ドライバ、ローカルアセットをサポートしています。

ネイティブ ES モジュール

Nuxt 3（および Bridge）は Native ES Modules を使用しています。
このガイドでは、ES モジュールとは何か、また Nuxt アプリ（または上流のライブラリ）を ESM に対応させる方法について説明します。

背景

CommonJS モジュール

CommonJS (CJS) は Node.js によって導入されたフォーマットで、分離された JavaScript モジュール間で機能を共有することができます (詳しくはこちら)。この構文にはすでに馴染みがあるかもしれません:

const a = require('./a')

module.exports.a = a

webpack や Rollup などのバンドラーはこの構文に対応しており、CommonJS で書かれたモジュールをブラウザで利用することができます。

ESM の構文

ESM vs CJS について話すとき、ほとんどの場合、モジュール を記述するための異なる構文について話しているのです。

import a from './a'

export { a }

ECMAScript Modules（ESM） が標準になる前に（10 年以上かかった！）、webpack のようなツールや TypeScript のような言語でさえ、いわゆる ESM 構文 をサポートするようになりました。しかし、実際の仕様とはいくつかの重要な違いがあります; ここでは 役に立つ説明 をしています。

'ネイティブ' ESM とは？

あなたは長い間、ESM 構文を使ってアプリを書いてきたかもしれません。Nuxt 2 では、あなたが書いたすべてのコードを適切なフォーマット（サーバは CJS、ブラウザは ESM）にコンパイルしています。

パッケージにインストールするモジュールを使用する場合は、少し事情が異なりました。サンプルライブラリは、CJS 版と ESM 版の両方を公開しており、どちらを使うか選択できるようになっています:

{
  "name": "sample-library",
  "main": "dist/sample-library.cjs.js",
  "module": "dist/sample-library.esm.js"
}

つまり、Nuxt 2 では、バンドル (webpack) はサーバビルド用に CJS ファイル ('main') を取り込み、クライアントビルド用に ESM ファイル ('module') を使用することになります。

しかし、最近の Node.js LTS リリースでは、Node.js の中で ネイティブの ESM モジュールを使用する ことができるようになりました。つまり、デフォルトではありませんが、Node.js 自体が ESM 構文を使って JavaScript を処理できるようになったのです。ESM 構文を有効にする最も一般的な方法は、次の 2 つです:

• package.json で type: 'module' を設定し、拡張子は .js を使用し続ける。
• .mjs のファイル拡張子を使用する（推奨）

Nuxt Nitro では、このように .output/server/index.mjs ファイルを出力しています。これは、Node.js にこのファイルをネイティブ ES モジュールとして扱うように指示するものです。

Node.js の文脈で有効なインポートとは何ですか？

モジュールを require するのではなく import する場合、Node.js は異なる方法でモジュールを解決します。例えば、sample-library を import すると、Node.js は main ではなく、そのライブラリの package.json にある exports や module のエントリを探します。

これは、const b = await import('sample-library') のような動的インポートにも当てはまります。

Node は以下の種類のインポートをサポートしています（docs を参照）。

1. .mjs で終わるファイル - ESM 構文を使用することが想定されています。
2. .cjs で終わるファイル - CJS 構文を使用することが想定されています。
3. .js で終わるファイル - package.json に type: 'module' がない限り、CJS 構文を使用することが期待されます。

どのような問題があるのでしょうか？

長い間、モジュールの作者は ESM 構文のビルドを作成してきましたが、.esm.js や .es.js といった規約を使用していました。これは今まで問題にはならなかったのですが、webpack のようなファイル拡張子を特に気にしない bundler によってのみ使用されてきたからです。

しかし、Node.js の ESM コンテキストで .esm.js ファイルを持つパッケージをインポートしようとすると、うまくいかず、次のようなエラーが表示されます:

(node:22145) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
/path/to/index.js:1

export default {}
^^^^^^

SyntaxError: Unexpected token 'export'
    at wrapSafe (internal/modules/cjs/loader.js:1001:16)
    at Module._compile (internal/modules/cjs/loader.js:1049:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    ....
    at async Object.loadESM (internal/process/esm_loader.js:68:5)

また、Node.js が CJS とみなしている ESM-syntax ビルドからの名前付きインポートがある場合にも、このエラーが発生する可能性があります:

file:///path/to/index.mjs:5
import { named } from 'sample-library'
         ^^^^^
SyntaxError: Named export 'named' not found. The requested module 'sample-library' is a CommonJS module, which may not support all module.exports as named exports.

CommonJS modules can always be imported via the default export, for example using:

import pkg from 'sample-library'
const { named } = pkg

    at ModuleJob._instantiate (internal/modules/esm/module_job.js:120:21)
    at async ModuleJob.run (internal/modules/esm/module_job.js:165:5)
    at async Loader.import (internal/modules/esm/loader.js:177:24)
    at async Object.loadESM (internal/process/esm_loader.js:68:5)

ESM 問題のトラブルシューティング

これらのエラーが発生した場合、ほぼ間違いなく上流のライブラリに問題があります。上流のライブラリは Node でインポートできるように ライブラリを修正する 必要があります。

ライブラリのトラインスパイル

その間、build.transpile にこれらのライブラリを追加することで、Nuxt にこれらのライブラリをインポートしようとしないように指示することができます。

import { defineNuxtConfig } from 'nuxt3'

export default defineNuxtConfig({
  build: {
    transpile: ['sample-library']
  }
})

また、これらのライブラリによってインポートされる他のパッケージを追加する必要があることが分かるかもしれません。

ライブラリのエイリアス

また、場合によっては、CJS バージョンのライブラリに手動でエイリアスを設定する必要があることもあります。

import { defineNuxtConfig } from 'nuxt3'

export default defineNuxtConfig({
  alias: {
    'sample-library': ['sample-library/dist/sample-library.cjs.js']
  }
})

デフォルトのエクスポート

CommonJS 形式の依存関係では、module.exports または exports を使用して、デフォルトのエクスポートを提供することができます:

module.exports = { test: 123 }
// or
exports.test = 123

require を使うこのような依存関係が必要な場合は、通常うまくいきます。

const pkg = require('cjs-pkg')

console.log(pkg) // { test: 123 }

Node.js のネイティブ ESM モード、esModuleInterop` を有効にした typescript、Webpack などのバンドラーでは、このようなライブラリをデフォルトでインポートできる互換性の仕組みが提供されています。この仕組みは、しばしば "interop require default" と呼ばれます:

import pkg from 'cjs-pkg'

console.log(pkg) // { test: 123 }

しかし、構文検出が複雑であったり、バンドル形式が異なるため、デフォルトの interop に失敗して、以下のような結果になる可能性があります。

import pkg from 'cjs-pkg'

console.log(pkg) // { default: { test: 123 } }

また、動的インポート構文（CJS ファイルと ESM ファイルの両方）を使用する場合、常にこのような状況が発生します:

ライブラリ作者のためのガイド

ESM の互換性の問題は、比較的簡単に解決できるのが良いところです。主に 2 つのオプションがあります。

1. ESM ファイルの名前を変更し、末尾を .mjs にすることができます。
   これは推奨される最もシンプルな方法です。ライブラリの依存関係やビルドシステムの問題を解決する必要があるかもしれませんが、ほとんどの場合、この方法で問題が解決されるはずです。また、CJS ファイルの名前を変更して、末尾を .cjs にすると、より明確になります。
2. ライブラリ全体を ESM のみにすることもできます。
   これは、package.json で type: 'module' を設定し、ビルドされたライブラリが ESM 構文を使用することを保証することを意味します。しかし、依存関係の問題に直面する可能性があります - このアプローチは、あなたのライブラリは、ESM コンテキストでのみ消費できることを意味します。

移行

CJS から ESM への最初のステップは、require の使用法を import に変更することです:

module.exports = ...

exports.hello = ...

or

export default ...

export const hello = ...

const myLib = require('my-lib')

or

import myLib from 'my-lib'
// or
const myLib = await import('my-lib').then(lib => lib.default || lib)

ESM モジュールでは、CJS と異なり、require、 require.resolve、 __filename、 __dirname グローバルは使用できないので、import()、 import.meta.filename に置き換えてください。

unjs/mlly の createCommonJS を使って、ESM に CJS 互換のコンテキストを作ることができます (あるいはインライン shim を使う)。

import { createCommonJS } from 'mlly'

const { __dirname, __filename, require } = createCommonJS(import.meta.url)

or

import { fileURLToPath } from 'url'
import { dirname } from 'path'
import { createRequire } from 'module'

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
const require = createRequire(import.meta.url)

const someFile = require.resolve('./lib/foo.js')

or

import { resolvePath } from 'mlly'

const someFile = await resolvePath('my-lib', { url: import.meta.url })

ベストプラクティス

• デフォルトのエクスポートではなく、名前付きのエクスポートを優先します。これは CJS のコンフリクトを減らすのに役立ちます。(デフォルトエクスポート のセクションを参照)
• Node.js のビルトインや CommonJS、Node.js のみへの依存はできるだけ避け、Nitro のポリフィルを必要とせずにブラウザや Edge Worker で使用できるライブラリにすること。
• 条件付きエクスポートで新しい エクスポート フィールドを使用する（続きを読む）。

{
  "exports": {
    ".": {
      "import": "./dist/mymodule.mjs"
    }
  }
}

TypeScript

Nuxt 3 は完全に型付けされており、コーディング時に正確な型情報にアクセスできるよう、便利なショートカットを提供しています。

型チェック

Nuxt は、パフォーマンス上の理由から、nuxi dev や nuxi build を実行する際にデフォルトで型チェックを行いません。しかし、nuxi を使用して手動で型をチェックすることができます。

yarn nuxi typecheck

自動生成される型

nuxi dev や nuxi build を実行すると、IDE の型サポート（と型チェック）のために、以下のファイルが生成されます。

.nuxt/nuxt.d.ts
このファイルには、使用しているすべてのモジュールの型と、Nuxt 3 が必要とする主要な型が含まれています。IDE はこれらのタイプを自動的に認識するはずです。

ファイル内のいくつかの参照は、buildDir (.nuxt)内にのみ生成されるファイルであるため、完全な型付けのためには、nuxi dev または nuxi build を実行する必要があります。

.nuxt/tsconfig.json
このファイルには、Nuxt や使用しているモジュールによって注入された解決済みのエイリアスを含む、プロジェクトに推奨される TypeScript の基本設定が含まれており、~/file や #build/file といったエイリアスに対して、フルタイプのサポートとパスの自動補完を行うことができます。

この設定を拡張する方法については、こちらをご覧ください。

より厳密な型チェック

TypeScript は、プログラムの安全性と解析性を高めるために、ある種のチェック機能を備えています。

コードベースを TypeScript に変換し、使い慣れたら、これらのチェックを有効にすることで、より安全性を高めることができます。(続きを読む)

厳密な型チェックを有効にするためには、nuxt.config を更新する必要があります:

export default defineNuxtConfig({
  typescript: {
    strict: true
  }
})

Nuxt ディレクトリ

.nuxt/ ディレクトリは、開発中の Nuxt が Vue アプリケーションを生成するために使用されます。

このディレクトリは、あなたが、ディレクトリ構造に基づいて Nuxt が生成するファイルについてもっと学びたい場合に興味深いものです。

Output ディレクトリ

output/ ディレクトリは、Nuxt がアプリケーションを本番用にビルドする際に作成されます。

このディレクトリは、Nuxt アプリケーションを本番環境にデプロイする際に使用されるように作られています。詳しくは、デプロイメントのセクション をご覧ください。

Assets ディレクトリ

assets/ ディレクトリは、ビルドツール（Webpack または Vite）で処理されるすべての Web サイト資源を追加するために使用されます。

このディレクトリには、通常、次のような種類のファイルが含まれています:

• スタイルシート（CSS、SASS など）
• フォント
• public/ ディレクトリから配信されない画像。

サーバーからアセットを提供したい場合は、public/ ディレクトリを参照することを推奨します。

Components ディレクトリ

components/ ディレクトリには、すべての Vue コンポーネントを配置し、pages や他のコンポーネントの中に取り込むことができます（詳細はこちら）。

Nuxt は components/ ディレクトリにあるコンポーネントを自動的にインポートします（使用しているモジュールによって登録されているコンポーネントも同様です）。

| components/
--| TheHeader.vue
--| TheFooter.vue

<template>
  <div>
    <TheHeader />
    <slot />
    <TheFooter />
  </div>
</template>

コンポーネントの名前

以下のような、ネストされたディレクトリにコンポーネントがある場合:

| components/
--| base/
----| foo/
------| Button.vue

...すると、コンポーネントの名前は、それ自身のパスディレクトリとファイル名に基づいて、重複するセグメントは削除されます。したがって、コンポーネントの名前は次のようになります:

<BaseFooButton />

動的なコンポーネント

Vue の <component :is="someComputedComponent"> 構文を使用したい場合は、Vue が提供する resolveComponent ヘルパーを使用する必要があります。

例えば:

<template>
  <component :is="clickable ? MyButton : 'div'" />
</template>

<script setup>
const MyButton = resolveComponent('MyButton')
</script>

また、推奨はしませんが、すべてのコンポーネントをグローバルに登録することもできます。この場合、すべてのコンポーネントに対して非同期チャンクが作成され、アプリケーション全体で利用できるようになります。

  import { defineNuxtConfig } from 'nuxt3'
  
  export default defineNuxtConfig({
    components: {
+     global: true,
+     dirs: ['~/components']
    },
  })

動的なインポート

コンポーネントを動的にインポートする（コンポーネントの lazy-loading とも呼ばれる）ために必要なことは、コンポーネントの名前に Lazy というプレフィックスを追加することです。

<template>
  <div>
    <TheHeader />
    <slot />
    <LazyTheFooter />
  </div>
</template>

これは、コンポーネントが常に必要とされるわけではない場合に特に有効です。Lazy プレフィックスを使用すると、適切なタイミングまでコンポーネントコードの読み込みを遅らせることができ、JavaScript のバンドルサイズを最適化するのに便利です。

<template>
  <div>
    <h1>Mountains</h1>
    <LazyMountainsList v-if="show" />
    <button v-if="!show" @click="show = true">Show List</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      show: false
    }
  }
}
</script>

<ClientOnly> コンポーネント

Nuxt は、意図的にクライアント側のみでコンポーネントをレンダリングするための <ClientOnly> コンポーネントを提供します。クライアントにのみコンポーネントをインポートするには、クライアントサイドのみのプラグインにコンポーネントを登録します。

<template>
  <div>
    <Sidebar />
    <ClientOnly>
      <!-- このコンポーネントは、クライアントサイドでのみレンダリングされます -->
      <Comments />
    </ClientOnly>
  </div>
</template>

クライアント側で <ClientOnly> がマウントされるまでのフォールバック（システムの一部に障害が発生したとき、システム全体の運転を停止させることなく、違った方法で処理を行うこと）として、スロットを使用します。

<template>
  <div>
    <Sidebar />
    <ClientOnly>
      <!-- このコンポーネントは、クライアントサイドでのみレンダリングされます -->
      <Comments />
      <template #fallback>
        <!-- これはサーバーサイドでレンダリングされます -->
        <p>Loading comments...</p>
      </template>
    </ClientOnly>
  </div>
</template>

ライブラリ作者

自動 tree shake（実行されないコードを削除すること）とコンポーネント登録ができる Vue コンポーネントライブラリの作成が超簡単です✨

components:dirs フックを使用すると、Nuxt モジュールにユーザー設定をすることなく、簡単にディレクトリリストを拡張することができます。

このようなディレクトリ構造をイメージしてください:

| node_modules/
---| awesome-ui/
------| components/
---------| Alert.vue
---------| Button.vue
------| nuxt.js
| pages/
---| index.vue
| nuxt.config.js

そして、awesome-ui/nuxt.js で components:dirs フックを使用することができます:

import { join } from 'pathe'
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  hooks: {
    'components:dirs'(dirs) {
      // ./components ディレクトリをリストに追加する
      dirs.push({
        path: join(__dirname, 'components'),
        prefix: 'awesome'
      })
    }
  }
})

以上です！これで、あなたのプロジェクトでは、nuxt.config ファイルで UI ライブラリを Nuxt モジュールとしてインポートすることができます:

export default {
  buildModules: ['awesome-ui/nuxt']
}

... そして、モジュールコンポーネント（接頭辞が awesome-）を直接 pages/index.vue で使用します:

<template>
  <div>
    My <AwesomeButton>UI button</AwesomeButton>!
    <awesome-alert>Here's an alert!</awesome-alert>
  </div>
</template>

使用する場合のみ自動的にコンポーネントをインポートし、node_modules/awesome-ui/components/ にあるコンポーネントを更新する際にも HMR（Hot Module Replacement、画面の再描画無しに JS の変更をブラウザに適用してくれるもの） をサポートするようにします。

Composables ディレクトリ

Nuxt 3 は composables/ ディレクトリをサポートしており、自動インポート機能を使って Vue の composables をアプリケーションに自動的にインポートすることができます !

ファイルのスキャン方法

composables/ ディレクトリのトップレベルにあるファイル（またはサブディレクトリ内のインデックスファイル）だけが、composables のスキャン対象となります。

例:

composables
 | - useFoo.ts
 | - useBar
 | --- supportingFile.ts
 | --- index.ts

useFoo.ts と useBar/index.ts だけがインポートとして検索され、後者がデフォルトのエクスポートであれば、index ではなく useBar として登録されるでしょう。

例（名前付き export を使用）

export const useFoo = () => {
  return useState('foo', () => 'bar')
}

例（default export を使用）

// useFoo()（拡張子なしのファイル名のキャメルケース）として利用可能になります
export default function () {
  return useState('foo', () => 'bar')
}

これで自動インポートができるようになりました:

<template>
  <div>
    {{ foo }}
  </div>
</template>

<script setup>
const foo = useFoo()
</script>

Layouts ディレクトリ

Nuxt は、アプリケーション全体で使用できるカスタマイズ可能なレイアウトフレームワークを提供し、共通の UI またはコードパターンを再利用可能なレイアウトコンポーネントに抽出するために理想的です。

レイアウトは、layouts/ ディレクトリに置かれ、使用時に非同期インポートによって自動的に読み込まれます。layouts/default.vue を作成すると、アプリ内のすべてのページでこのレイアウトが使用されます。その他のレイアウトは、ページのメタデータの一部として layout プロパティを設定するか（~/pages 統合を使用している場合）、<NuxtLayout> コンポーネントを使って使用されます。

アプリケーションにレイアウトが 1 つしかない場合は、代わりに app.vue を使用することができます。

例: app.vue でレイアウトを有効にする

-| layouts/
---| custom.vue
-| app.vue

レイアウトファイルでは、<slot /> を使って、レイアウトのコンテンツが読み込まれる場所を定義する必要があります。例えば:

<template>
  <div>
    一部のレイアウトコンテンツを共有
    <slot />
  </div>
</template>

そのレイアウトを app.vue でどのように使うかを説明します。

<template>
  <NuxtLayout name="custom">
    Hello world!
  </NuxtLayout>
</template>

例: ~/pages でレイアウトを設定する

-| layouts/
---| custom.vue
-| pages/
---| index.vue

このように、pages コンポーネントの中でレイアウトを設定することができます:

<script>
// これは、 `<script setup>` の内部でも同様に動作します
definePageMeta({
  layout: 'custom',
})
</script>

例: ~/pages による手動制御

たとえ ~/pages 統合を使っていても、<NuxtLayout> コンポーネント（アプリケーション全体でグローバルに利用可能）を使って layout: false を設定すれば、完全に制御することができます。

<template>
  <NuxtLayout name="custom">
    <template #header> Some header template content. </template>

    The rest of the page
  </NuxtLayout>
</template>

<script setup>
definePageMeta({
  layout: false,
})
</script>

例: レイアウトの変更

また、レイアウトに ref や computed プロパティを使用することもできます。

<template>
  <div>
    <button @click="enableCustomLayout">Update layout</button>
  </div>
</template>

<script setup>
const route = useRoute()
function enableCustomLayout () {
  route.meta.layout = "custom"
}
definePageMeta({
  layout: false,
})
</script>

Middleware ディレクトリ

Nuxt は、アプリケーション全体で使用できるカスタマイズ可能なルートミドルウェアフレームワークを提供し、特定のルートにナビゲートする前に実行したいコードを抽出するのに適しています。

ルートミドルウェアは 3 種類あります:

1. 匿名（またはインライン）ルートミドルウェアは、使用するページで直接定義されます。
2. 名前付きルートミドルウェアは、middleware/ ディレクトリに置かれ、ページで使用される際に非同期インポートによって自動的に読み込まれます。
3. グローバルルートミドルウェアは、middleware/ ディレクトリに置かれ（拡張子は .globalで）、ルートが変更されるたびに自動的に実行されるルートミドルウェアです。

最初の 2 種類のルートミドルウェア（匿名、名前付きルートミドルウェア）は、definePageMeta で定義することができます 。

フォーマット

ルートミドルウェアは、現在のルートと次のルートを引数として受け取るナビゲーションガードです。

export default defineNuxtRouteMiddleware((to, from) => {
  if (to.params.id === '1') {
    return abortNavigation()
  }
  return navigateTo('/')
})

Nuxt は、ミドルウェアから直接返すことができるグローバルに利用可能なヘルパーを 2 つ提供しています。

1. navigateTo (route: string | Route) - プラグインやミドルウェアの中で、指定されたルートにリダイレクトします。また、クライアントサイドで直接呼び出すこともできて、ページナビゲーションを実行します。
2. abortNavigation (err?: string | Error) - オプションのエラーメッセージとともに、ナビゲーションを中止します。

vue-router のドキュメント にあるナビゲーションガードとは異なり、3 番目の next() 引数は渡されず、リダイレクトやルートのキャンセルは、ミドルウェアから値を返すことによって処理されます。可能な戻り値は以下の通りです:

• nothing - ナビゲーションをブロックせず、次のミドルウェア関数があればそれに移行するか、ルートナビゲーションを完了します。
• navigateTo('/') または navigateTo({ path: '/' }) - 指定されたパスにリダイレクトします。
• abortNavigation() - 現在のナビゲーションを停止します。
• abortNavigation(error) - エラーで現在のナビゲーションを拒否します。

ミドルウェアを動的に追加する

プラグインなどのヘルパー関数 addRouteMiddleware() を使って、 グローバルまたは名前つきルートミドルウェアを手動で追加することができます。

export default defineNuxtPlugin(() => {
  addRouteMiddleware('global-test', () => {
    console.log('このグローバルルートミドルウェアはプラグインで追加され、ルート変更のたびに実行されます')
  }, { global: true })

  addRouteMiddleware('named-test', () => {
    console.log('この名前付きミドルウェアはプラグインで追加され、既存の同名のミドルウェアを上書きします')
  })
})

例: 名前付きルートミドルウェア

-| middleware/
---| auth.ts

ページファイル内で、このルートミドルウェアを参照することができます。

<script setup>
definePageMeta({
  middleware: ["auth"]
  // or middleware: 'auth'
})
</script>

さて、そのページへのナビゲーションが完了する前に、auth ルートミドルウェアが実行されます。

Node modules ディレクトリ

node_modules ディレクトリは、パッケージマネージャ（npm または yarn ）によって作成され、プロジェクトの依存関係を保存します。

Pages ディレクトリ

Nuxt は、Vue Router を裏で使用して、Web アプリケーション内にルートを作成するためのファイルベースのルーティングを提供します。

使い方

pages は、Vue コンポーネントで、拡張子は vue、js、tss または tsx です。

<template>
  <h1>Index page</h1>
</template>

or

// https://vuejs.org/guide/extras/render-function.html
export default defineComponent({
  render () {
    return h('h1', 'Index page')
  }
})

or

// https://vuejs.org/guide/extras/render-function.html#jsx-tsx
export default defineComponent({
  render () {
    return <h1>Index page</h1>
  }
})

pages/index.vue ファイルは、アプリケーションの / ルートにマップされます。

app.vue を使用している場合は、<NuxtPage /> コンポーネントを使用して、現在のページを表示することを確認してください。

<template>
  <div>
    <!-- 全ページで共有されるマークアップ（例: NavBar） -->
    <NuxtPage />
  </div>
</template>

動的なルート

角括弧（[]）の中に何かを入れると、それが 動的なルート のパラメータになります。複数のパラメータを混在させたり、ファイル名やディレクトリ内の非ダイナミックテキストも混在させることができます。

例

-| pages/
---| index.vue
---| users-[group]/
-----| [id].vue

上記の例では、$route オブジェクトを介してコンポーネント内の group/id にアクセスすることができます:

<template>
  <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
</template>

users-admins/123 に移動するとレンダリングされます:

<p>admins - 123</p>

Composition API を使ってルートにアクセスしたい場合は、 グローバルな useRoute 関数を使えば、 Options API の this.$route と同じようにルートにアクセスすることができます。

<script setup>
const route = useRoute()

if (route.params.group === 'admins' && !route.params.id) {
  console.log('Warning! Make sure user is authenticated!')
}
</script>

Catch all ルート

catch-all ルート（Next.js にあるやつ）が必要な場合は、[...slug].vue のような名前のファイルを使用して作成します。これは、そのパスの下にある すべての ルートにマッチするので、非ダイナミック・テキストをサポートしません。

<template>
  <p>{{ $route.params.slug }}</p>
</template>

/hello/world に移動するとレンダリングされます:

<p>["hello", "world"]</p>

ネストしたルート

<NuxtPage> を使用して、ネストしたルート を表示することができます。

例:

-| pages/
---| parent/
------| child.vue
---| parent.vue

このファイルツリーは、これらのルートを生成します:

[
  {
    path: '/parent',
    component: '~/pages/parent.vue',
    name: 'parent',
    children: [
      {
        path: 'child',
        component: '~/pages/parent/child.vue',
        name: 'parent-child'
      }
    ]
  }
]

child.vue コンポーネントを表示するには、pages/parent.vue の中に <NuxtPage> コンポーネントを挿入する必要があります:

<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :foobar="123" />
  </div>
</template>

子ルートキー

<NuxtPage> コンポーネントが再レンダリングされるタイミングをより細かく制御したい場合（例えば、遷移のため）、pageKey プロパティを通じて文字列または関数を渡すか、definePageMeta を通じて key 値を定義することが可能です:

<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :page-key="someKey" />
  </div>
</template>

もしくは、代わりとして:

<script setup>
definePageMeta({
  key: route => route.fullPath
})
</script>

ページメタデータ

アプリ内の各ルートに対してメタデータを定義したい場合があります。これは、definePageMeta マクロを使用して行うことができ、<script> と <script setup> の両方で機能します:

<script setup>
definePageMeta({
  title: 'My home page'
})
</script>

このデータは、アプリの残りの部分で route.meta オブジェクトからアクセスすることができます。

<script setup>
const route = useRoute()
console.log(route.meta.title) // 自分のホームページ
</script>

ネストされたルートを使用している場合、これらすべてのルートからのページメタデータは、単一のオブジェクトにマージされます。ルートメタの詳細については、vue-router のドキュメントを参照してください。

defineEmits や defineProps（Vue のドキュメント を参照）と同様に、definePageMeta は コンパイラマクロ です。これはコンパイルされてしまうので、コンポーネント内で参照することはできません。その代わり、このマクロに渡されたメタデータは、コンポーネントの外に持ち出されます。したがって、ページメタオブジェクトはコンポーネント（またはコンポーネント上で定義された値）を参照することはできません。しかし、インポートされたバインディングを参照することはできます。

<script setup>
import { someData } from '~/utils/example'

const title = ref('')

definePageMeta({
  title,  // これはエラーになります
  someData
})
</script>

特別なメタデータ

もちろん、アプリ内で使用するメタデータは自由に定義していただいてかまいません。しかし、definePageMeta で定義されるメタデータの中には、特定の目的を持ったものがあります:

keepalive

Nuxt は definePageMeta で keepalive: true を設定すると、自動的に Vue の <KeepAlive> コンポーネント でページをラップしてくれます。これは、例えば、動的な子ルートを持つ親ルートで、ルートが変わってもページの状態を保持したい場合に便利でしょう。また、<KeepAlive> に渡す props を設定することもできます（詳しくは こちら をご覧ください）。

key

ルートキーの項目を確認してください。

layout

ルートのレンダリングに使用するレイアウトを定義することができます。これは false （レイアウトを無効にする）、文字列、または何らかの方法で反応させたい場合は ref/computed のいずれかになります。詳細は、レイアウトディレクトリの項目をご覧ください。

middleware

このページを読み込む前に適用するミドルウェアを定義することができます。このミドルウェアは、一致する親子ルートで使用されている他のすべてのミドルウェアと統合されます。文字列、関数（global before guard パターン に従った匿名/インライン化されたミドルウェア関数）、または文字列/関数の配列が利用できます。詳細は、名前付きミドルウェア の項目をご覧ください。

layoutTransition と pageTransition

ページやレイアウトをラップする <transition> コンポーネントに遷移のプロパティを定義したり、false を渡してそのルートの <transition> ラッパーを無効にしたりすることが可能です。詳細は、トランジション の項目をご覧ください。

ナビゲーション

アプリケーションのページ間を移動するには、<NuxtLink> コンポーネントを使用する必要があります。

このコンポーネントは Nuxt に含まれているため、他のコンポーネントのようにインポートする必要はありません。

HTML の <a> タグと似ていますが、href="/about" の代わりに to="/about" を使用する点が異なります。vue-router を使ったことがあるなら、<NuxtLink> は <RouterLink> の代わりと考えることができます。

これは、pages フォルダーにある index.vue のページへのシンプルなリンクです:

<template>
  <NuxtLink to="/">Home page</NuxtLink>
</template>

また、<NuxtLink> コンポーネントは、すべての内部リンクに使用する必要があります。つまり、サイト内のページへのリンクはすべて <NuxtLink> を使用する必要があります。<a> タグは、すべての外部リンクに使用されます。つまり、他のサイトへのリンクは <a> タグを使用します。

<template>
  <div>
    <h1>Home page</h1>
    <NuxtLink to="/about">
      About (internal link that belongs to the Nuxt App)
    </NuxtLink>
    <a href="https://nuxtjs.org">External Link to another page</a>
  </div>
</template>

ルーターオプション

デフォルトの vue-router のオプションを設定することができます。

注意: history と routes のオプションは、常に Nuxt によってオーバーライド（ある場所で定義された設定や属性などを、別の定義で上書きすること）されます。

app/router.options の使い方

ルーターオプションの指定には、この方法が推奨されます。

import type { RouterOptions } from '@nuxt/schema'

// https://router.vuejs.org/api/#routeroptions
export default <RouterOptions>{
}

nuxt.config の使い方

注意: JSON シリアライズ（オプジェクト化されたデータを JSON 文字列に変換すること）可能なオプションのみ設定可能です。

• linkActiveClass
• linkExactActiveClass
• end
• sensitive
• strice

export default defineNuxtConfig({
  router: {
    // https://router.vuejs.org/api/#routeroptions
    options: {}
  }
})

Plugins ディレクトリ

Nuxt は plugins ディレクトリにあるファイルを自動的に読み込んでロードします。ファイル名に .server または .client という接尾辞を使用すると、サーバサイドまたはクライアントサイドでのみプラグインを読み込むことができます。

どのファイルが登録されるか

plugins/ ディレクトリのトップレベルにあるファイル（またはサブディレクトリ内のインデックスファイル）だけがプラグインとして登録されます。

例えば:

plugins
 | - myPlugin.ts
 | - myOtherPlugin
 | --- supportingFile.ts
 | --- componentToRegister.vue
 | --- index.ts

myPlugin.ts と myOtherPlugin/index.ts のみが登録されることになります。

プラグインを作成する

プラグインに渡される唯一の引数は nuxtApp です。

export default defineNuxtPlugin(nuxtApp => {
  // nuxtApp でなにかする
})

自動的にヘルパーを提供する

NuxtApp インスタンスにヘルパーを提供したい場合、プラグインからヘルパーをprovide キーで返します。例えば:

export default defineNuxtPlugin(() => {
  return {
    provide: {
      hello: () => 'world'
    }
  }
})

別のファイルで、これを使うことができます:

<template>
  <div>
    {{ $hello() }}
  </div>
</template>

<script setup lang="ts">
// または、このように使うこともできます
const { $hello } = useNuxtApp()
</script>

タイピングプラグイン

プラグインからヘルパーを返すと、自動的に型付けされます。useNuxtApp() の戻り値やテンプレート内で型付けされているのがわかると思います。

高度なプラグイン

高度な使用例では、以下のように注入されたプロパティの型を宣言することができます:

declare module '#app' {
  interface NuxtApp {
    $hello (msg: string): string
  }
}

declare module '@vue/runtime-core' {
  interface ComponentCustomProperties {
    $hello (msg: string): string
  }
}

export { }

Vue プラグイン

Google Analytics のタグを追加する vue-gtag のように、Vue のプラグインを使用したい場合は、Nuxt のプラグインを使用することができます。

これをもっと簡単にするための Open RFC（Request for Comments、インターネット技術の標準的な仕様を記した文書）があります！nuxt/framework#1175 を参照してください。

まず、必要なプラグインをインストールします。

yarn add --dev vue-gtag-next

それから、プラグインファイル plugins/vue-gtag.client.js を作成します。

import VueGtag from 'vue-gtag-next'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(VueGtag, {
    property: {
      id: 'GA_MEASUREMENT_ID'
    }
  })
})

Public ディレクトリ

public/ ディレクトリは、サーバールートに直接提供され、名前を維持しなければならない（例: robots.txt）、またはおそらく変更されない（例: favicon.ico）公開ファイルを含んでいます。

Server ディレクトリ

Nuxt は、server/ ディレクトリを使用して、アプリケーションのあらゆるバックエンドロジックを作成します。HMR（Hot Module Replacement、画面の再描画なしに JS の変更をブラウザに適用する機能）をサポートし、強力な機能を備えています。

server/ ディレクトリには、プロジェクトで使用する API エンドポイントやサーバーミドルウェアが含まれます。

API ルート

Nuxt は、~/server/api ディレクトリにあるファイルを自動的に読み込んで、API エンドポイントを作成します。

各ファイルは、API リクエストを処理するデフォルトの関数をエクスポートする必要があります。これは、promise または JSON データを直接返すことができます（または、res.end() を使用します）。

例

Hello World

export default (res, req) => 'Hello World'

http://localhost:3000/api/hello で結果をご覧ください。

Async 関数

export default async (req, res) => {
  await someAsyncFunction()

  return {
    someData: true
  }
}

例: Node.js を使ったスタイル

import type { IncomingMessage, ServerResponse } from 'http'

export default async (req: IncomingMessage, res: ServerResponse) => {
  res.statusCode = 200
  res.end('Works!')
}

リクエストデータへのアクセス

import { useBody, useCookies, useQuery } from 'h3'

export default async (req, res) => {
  const query = useQuery(req)
  const body = await useBody(req) // only for POST request
  const cookies = useCookies(req)
  
  return { query, body, cookies }
}

詳しくは、he methods をご覧ください。

サーバーミドルウェア

Nuxt は、~/server/middleware にあるファイルを自動的に読み込んで、プロジェクト用のサーバーミドルウェアを作成します。

これらのファイルは、独自のルートにマッピングされる API ルート とは異なり、すべてのリクエストで実行されます。これは、通常すべてのレスポンスに共通のヘッダーを追加したり、レスポンスを記録したり、リクエストチェーン（最初の API コールから返されたデータを使って、別のAPIコールを行うこと）であとで使えるように受信リクエストオブジェクトを変更したりするためです。

各ファイルは、リクエストを処理するためのデフォルトの関数をエクスポートする必要があります。

export default async (req, res) => {
  req.someValue = true
}

req/res オブジェクトにはなんの違いもないので、タイプするのは簡単です。

import type { IncomingMessage, ServerResponse } from 'http'

export default async (req: IncomingMessage, res: ServerResponse) => {
  req.someValue = true
}

アプリケーションのより深い部分にリクエストを渡すには、関数の内部で返すことができます。

export default async (req, res) => {
  const isNotHandledByThisMiddleware = req.url.includes('/some-unhandled-url-path/')
  if(isNotHandledByThisMiddleware) {
    return
  }

  // ここに実際のロジックを書く
}

Gitignore ファイル

.gitignore ファイルは、git が無視すべき、意図的に追跡されていないファイルを指定します。詳しくは、git のドキュメントをご覧ください。

.gitignore ファイルには、少なくとも 以下の項目を記述しておくことを推奨します。

# Nuxt dev/build 出力
.output
.nuxt
# Node 依存関係
node_modules
# システムファイル
*.log

App ファイル

app.vue ファイルは、Nuxt 3 アプリケーションの主要なコンポーネントです。

最小限の使い方

Nuxt 3 では、pages/ ディレクトリはオプションです。存在しない場合、Nuxt は vue-router の依存関係を含めません。これは、ランディングページやルーティングを必要としないアプリケーションで作業するときに便利です。

<template>
  <h1>Hello World!</h1>
</template>

pages ディレクトリの使い方

pages/ ディレクトリがある場合、現在のページを表示するには、<NuxtPage> コンポーネントを使用します:

<template>
  <div>
    <NuxtLayout>
      <NuxtPage/>
    </NuxtLayout>
  </div>
</template>

あなたが、ページ間のページ周りの構造をカスタマイズする可能性があるなら、layout/ ディレクトリをチェックしてみてください。

Nuxt 設定ファイル

Nuxt は、拡張子が .js, .ts, .mjs のいずれかの nuxt.config ファイル 1 つで簡単に設定することができます。

import { defineNuxtConfig } from 'nuxt3'

export default defineNuxtConfig({
  // 自分の Nuxt の設定
})

すべての異なる設定プロパティを確認する。

alias

• Type: object
• Default

{
  "~~": "/<rootDir>",
  "@@": "/<rootDir>",
  "~": "/<rootDir>",
  "@": "/<rootDir>",
  "assets": "/<rootDir>/assets",
  "public": "/<rootDir>/public"
}

• Version: 2, 3

JavaScript や CSS 内のカスタムディレクトリにアクセスするためのエイリアスを追加定義することで、DX を向上させることができます。

例:

import { resolve } from 'pathe'
export default {
  alias: {
    'images': resolve(__dirname, './assets/images'),
    'style': resolve(__dirname, './assets/style'),
    'data': resolve(__dirname, './assets/other/data')
  }
}

app

Nuxt アプリの構成

baseURL

• Type: string
• Default

"/"

• Version: 2, 3

Nuxt アプリケーションの基本パス。

これは、環境変数 BASE_PATH を設定することで、実行時に設定することができます。

BASE_PATH=/prefix/ node .output/server/index.mjs

buildAssetsDir

buildDir

• Type: string
• Default

"/_nuxt/"

• Version: 2, 3

構築されたサイトアセットのフォルダ名で、baseURL（設定されている場合は cdnURL）に対する相対パスです。これは構築時に設定されるため、実行時にカスタマイズする必要はありません。

cdnURL

• Default

null

• Version: 2, 3

公開フォルダを提供する絶対 URL（本番環境のみ）。

これは、環境変数 CDN_URL の設定により、実行時に別の値を設定することができます。

例:

CDN_URL=https://mycdn.org/ node .output/server/index.mjs

buildModules

• Type: array
• Version: 2, 3

開発・ビルド時にのみ必要とされるモジュール。

モジュールは Nuxt の拡張機能で、コア機能を拡張し、無限の統合機能を追加することができます。 各モジュールは文字列（パッケージを参照したり、ファイルへのパス）、最初の文字列がモジュール、2 番目のオブジェクトがオプションのタプル、またはインラインモジュール関数のいずれかです。Nuxt はモジュール配列の各アイテムを node require path (node_modules の中で) を使って解決しようとし、~ alias が使われている場合はプロジェクトの srcDir から解決されます。

例:

modules: [
  // Using package name
  '@nuxtjs/axios',
  // Relative to your project srcDir
  '~/modules/awesome.js',
  // Providing options
  ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
  // Inline definition
  function () {}
]

css

• Type: array
• Version: 2, 3

グローバルに設定したい（すべてのページに含まれる）CSSファイル/モジュール/ライブラリを定義することができます。

Nuxt は拡張子から自動的にファイルの種類を推測し、適切なプリプロセッサを使用します。ただし、必要なローダーを使用する場合は、インストールする必要があります。

例:

css: [
  // Load a Node.js module directly (here it's a Sass file)
  'bulma',
  // CSS file in the project
  '@/assets/css/main.css',
  // SCSS file in the project
  '@/assets/css/main.scss'
]

dev

dir

extends

extensions

hooks

ignore

ignoreOptions

ignorePrefix

meta

modules

postcss

privateRuntimeConfig

publicRuntimConfig

rootDir

serverMiddleware

srcDir

ssr

vite

watchers

webpack

Nuxt ignore ファイル

.nuxtignore ファイルを使用すると、ビルド時にプロジェクトのルートディレクトリ（rootDir）にある layout、pages、components、composables、middleware のファイルを Nuxt が無視するように設定できます。.nuxtignore ファイルは .gitignore や .eslintignore ファイルと同じ仕様で、各行が無視すべきファイルを示す glob パターン（ワイルドカードなどでファイルパスを表記できるもの）になっています。

注意: nuxt.config ファイルで ignoreOptions、ignorePrefix と ignore を設定することもできます。

例

# layout/foo.vue を無視する
layouts/foo.vue
# 最後に -ignore.vue と名の付く layout ファイルを無視する
layouts/*-ignore.vue

# pages/bar.vue を無視する
pages/bar.vue
# pages/ignore ディレクトリ下のファイルをすべて無視する
pages/ignore/*.vue

# middleware/foo/bar.js を除く middleware/foo ディレクトリ下のファイルをすべて無視する
middleware/foo/*.js
!middleware/foo/bar.js

詳細は、gitignore ドキュメントを確認してください。

Package ファイル

package.json ファイルはアプリケーションのすべての依存関係とスクリプトを含みます（詳細を確認する）。

TypeScript 設定ファイル

Nuxt は、Nuxt プロジェクトで使用している解決済みのエイリアスを含む .nuxt/tsconfig.json ファイル、および他の賢明なデフォルトを自動的に生成します。プロジェクトのルートに以下のような内容の tsconfig.json を作成することで、この恩恵を受けることができます。

必要に応じて、このファイルの内容をカスタマイズすることができます。ただし、パス をカスタマイズする必要がある場合、自動生成されたパスエイリアスを上書きしてしまうことに注意してください。その代わりに、必要なパスエイリアスは nuxt.config 内の alias プロパティに追加して、自動生成される tsconfig に取り込まれるようにすることをお勧めします。

概要

Nuxt 3 は Nuxt 2 の完全な書き直しであり、また新しい一連の基礎技術に基づくものです。つまり、Nuxt 2 のアプリを Nuxt 3 に移行する際には大きな変化が生じますが、安定版リリースに向けて移行はより簡単になると思われます。

これらの重要な変更点の一部を紹介します:

1. Composition API とscript setup のデフォルト化を含む Vue 2 から Vue 3 への移行
2. webpack 4 と Babel から Vite または webpack 5 と esbuild への移行
3. ランタイムの Nuxt 依存から、nitropack でコンパイルされた最小限のスタンドアローンサーバー（単独で動作しているシステム）に移行しました

構成

nuxt.config

Nuxt アプリケーションの出発点は、nuxt.config ファイルのままです。

📦 Nuxt の設定、`unjs/jiti` と `unjs/c12` を使用して読み込まれます。

移行

1. 型付き設定スキーマを提供する新しい関数 defineNuxtConfig に移行する必要があります。

export default {
  // ...
}

or

import { defineNuxtConfig } from 'nuxt3'

export default defineNuxtConfig({
  // ...
})

2. router.extendRoutes を使用していた場合、新しい pages/extend フックに移行できます:

export default {
  router: {
    extendRoutes (routes) {
      //
    }
  }
}

or

import { defineNuxtConfig } from 'nuxt3'

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (routes) {
      //
    }
  }
})

ESM 構文

Nuxt 3 は、ESM ネイティブフレームワーク です。unjs/jiti は、nuxt.config フィアルを読み込む際に半互換性を提供しますが、このファイルでは、require と module.exports の使用は避けてください。

1. module.exports を export default に変更する
2. const lib = require('lib') を import lib from 'lib' に変更する

Async 構成

Nuxt の読み込み動作をより予測しやすくするために、非同期設定構文は非推奨となります。非同期操作には、Nuxt フックを使用することを検討してください。

Dotenv

Nuxt は、.env ファイルを読み込むためのサポートを内蔵しています。nuxt.config から直接インポートするのは避けてください。

モジュール

Nuxt と Nuxt モジュールは、ビルド時のみになりました。

移行

1. buildModule をすべて module に移動させる
2. モジュールの Nuxt 3 との互換性を確認する

TypeScript

Nuxt の TypeScript の統合を使用すると、アプリケーションの移行がより簡単になります。これは、アプリケーションを TypeScript で書く必要があるということではなく、Nuxt がエディタに自動的に型ヒントを提供するということです。

Nuxt の TypeScript サポートについては ドキュメント を参照してください。

移行

1. 以下の内容で tsconfig.json を作成します

{
  "extends": "./.nuxt/tsconfig.json"
}

2. npx nuxi prepare を実行して、.nuxt/tsconfig.json を生成します
3. ドキュメント にある指示に従って Volar をインストールします

Vue の変更点

Vue のベストプラクティスとして推奨されているものに多くの変更があり、また Vue 2 と 3 の間には多くの破壊的な変更があります。

Vue 3 への移行ガイド と、特に 破壊的な変更点のリスト を読むことを推奨します。

現在、Nuxt 3 RC で Vue 3 の移行ビルドを使用することはできません。

Vuex

Nuxt は Vuex との統合を提供しなくなりました。代わりに、Vue の公式の推奨は、Nuxt モジュールを介して Nuxt サポートを内蔵している pinia を使用することです。pinia の詳細については、こちらをご覧ください 。

Vuex を使い続けたい場合は、以下の手順 で手動で Vuex 4 に移行することができます。

自動インポート

Nuxt 3 は、最小限の摩擦で済むアプローチを採用しており、可能な限りコンポーネントやコンポーザブルを自動でインポートすることができます。

自動インポートについてもっと読む

移行

1. Nuxt 2 で @nuxt/components を使用していた場合、nuxt.config の components: true を削除してください。もし、もっと複雑な設定をしていたのであれば、コンポーネントのオプションが多少変更されていることに注意してください。詳しくは、components のドキュメント をご覧ください。

メタタグ

Nuxt 3 では、メタタグを管理する方法がいくつか用意されています。

1. nuxt.config を通じて
2. useMeta コンポーザブルを通じて
3. グローバルメタコンポーネントを通じて

title、base、script、stye、meta、link、htmlAttrs、bodyAttrs をカスタマイズすることが可能です。

メタタグについてもっと読む。

移行

1. nuxt.config で、head を meta に名前変更してください。この共有された meta の設定を、代わりに app.vue に移行することを検討してください。（オブジェクトは、重複排除のための hid キーを持たなくなったことに注意してください）
2. コンポーネントでは、head オプションの名前を meta に変更します。コンポーネントの状態にアクセスする必要がある場合は、useMeta を使用するように移行する必要があります。また、内蔵のメタコンポーネントの使用も検討してください。

例: useMeta

<script>
export default {
  data: () => ({
    title: 'My App',
    description: 'My App Description'
  })
  head () {
    return {
      title: this.title,
      meta: [{
        hid: 'description',
        name: 'description',
        content: this.description
      }]
    }
  }
}
</script>

or

<script setup>
const title = ref('My App')
const description = ref('My App Description')

// This will be reactive even you change title/description above
useMeta({
  title,
  meta: [{
    name: 'description',
    content: description
  }]
})
</script>

例: 内蔵のメタコンポーネント

Nuxt 3 には、同じタスクを実行するために使用できるメタコンポーネントも用意されています。これらのコンポーネントは HTML タグに似ていますが、Nuxt によって提供され、同様の機能を備えています。

<script>
export default {
  head () {
    return {
      title: 'My App',
      meta: [{
        hid: 'description',
        name: 'description',
        content: 'My App Description'
      }]
    }
  }
}
</script>

or

<template>
  <div>
    <Head>
      <Title>My App</Title>
      <Meta name="description" content="My app description"/>
    </Head>
    <!-- -->
  </div>
</template>  

プラグインとミドルウェア

プラグイン

プラグインは異なるフォーマットを持ち、1 つの引数（nuxtApp） を取るようになりました。詳しくは、ドキュメント をご覧ください。

export default (ctx, inject) => {
  inject('injected', () => 'my injected function')
})

or

export default defineNuxtPlugin(nuxtApp => {
  // `nuxtApp.$injected` が使用可能になりました
  nuxtApp.provide('injected', () => 'my injected function')

  // 代わりにこのフォーマットは、自動型サポート付きです
  return {
    provide: {
      injected: () => 'my injected function'
    }
  }
})

移行

1. defineNuxtPlugin ヘルパー関数を使用するようにプラグインを移行します
2. plugins フォルダにある nuxt.cofig プラグイン配列のエントリーをすべて削除してください。このディレクトリのトップレベルにあるすべてのファイル（および任意のサブディレクトリにあるインデックスファイル）は自動的に登録されます。モードをクライアントまたはサーバーに設定する代わりに、ファイル名でそれを示すことができます。例えば、~/plugins/my-plugin.client.ts はクライアントサイドでのみ読み込まれます。

ルートミドルウェア

ルートミドルウェアは、別の形式を持ちます。

export default function ({ store, redirect }) {
  // ユーザーの認証がされていない場合
  if (!store.state.authenticated) {
    return redirect('/login')
  }
}

or

export default defineNuxtRouteMiddleware((to, from) => {
  const auth = useState('auth')
  if (!auth.value.authenticated) {
    return navigateTo('/login')
  }
})

Nuxt 2 と同様、~/middleware フォルダに配置されたルートミドルウェアが自動的に登録されます。そのあと、コンポーネントで名前を付けて指定することができます。ただし、これはコンポーネントのオプションとしてではなく、definePageMeta で行われます。

navigateTo は、いくつかのルートヘルパー関数のひとつで、詳細は ルートミドルウェアに関するドキュメント をご覧ください。

移行

1. defineNuxtRouteMiddleware ヘルパー関数を使用するようにルートミドルウェアを移行してください。
2. グローバルミドルウェア（nuxt.config など）は、例えば ~/middleware/auth.global.ts のように .global という拡張子をつけて ~/middleware フォルダに配置することができます。

pages とレイアウト

app.vue

Nuxt 3 は、~/app.vue を介してアプリへのセントラルエントリーポイントを提供します。もし、ソースディレクトリに app.vue ファイルがなければ、Nuxt は独自のデフォルトバージョンを使用します。

このファイルは、アプリの起動時に一度だけ実行する必要のあるカスタムコードや、アプリの各ページに存在するコンポーネントを置くのに最適な場所です。例えば、レイアウトが 1 つしかない場合は、代わりに app.vue に移動させることができます。

app.vue についてもっと読む

移行

1. app.vue ファイルを作成し、アプリのトップレベルで一度だけ実行する必要があるロジックを含めることを検討してください。ここで、その例を確認することができます 。

レイアウト

アプリで複数のページにレイアウトを使用している場合は、わずかな変更で済みます。

Nuxt 2 では、<Nuxt> コンポーネントはレイアウト内で現在のページをレンダリングするために使用されます。Nuxt 3 では、レイアウトは代わりにスロットを使用するため、そのコンポーネントを <slot /> に置き換える必要があります。これにより、名前付きスロットやスコープ付きスロットを使った高度なユースケースも可能になります。レイアウトについてもっと読む 。

また、definePageMeta コンパイラマクロを使用して、ページで使用されるレイアウトを定義する方法を変更する必要があります。レイアウトはケバブケースになります。
そのため、layouts/customLayout.vue は、ページ内で参照されると custom-layout になります。

移行

1. <Nuxt /> を <slot /> に置き換える。
2. definePageMeta を使って、ページで使用するレイアウトを選択します。
3. ~/layouts/_error.vue を ~/error.vue に移動します。エラー処理のドキュメント を参照してください。

例: ~/layouts/custom.vue

  <template>
    <div id="app-layout">
      <main>
-       <Nuxt />
+       <slot />
      </main>
    </div>
  </template>

  <script>
+ definePageMeta({ layout: 'custom' })
  export default {
-   layout: 'custom'
  }
  </script>

ページ

Nuxt 3 には、ソースディレクトリに pages/ ディレクトリが存在することをトリガーとして、vue-router の統合がオプションで用意されています。もし、1 ページしかないのであれば、app.vue に移動してビルドを軽くすることを検討してもよいでしょう。

動的なルート

Nuxt 3 の動的なルートの定義形式は Nuxt 2 と若干異なるため、pages/ 内のファイル名を一部変更する必要があるかもしれません。

1. 以前は動的経路のパラメータを定義するのに _id を使用していましたが、現在は [id] を使用します。
2. 以前は _.vue を使ってキャッチオールルートを定義していましたが、現在は [...slug].vue を使っています。

ネストされたルート

Nuxt 2 では、<Nuxt> と <NuxtChild> を使用して、（親と子のコンポーネントを持つ）ネストされたルートを定義していました。Nuxt 3 では、これらは単一の <NuxtPage> コンポーネントに置き換えられました。

Page key と keep-alive props

<Nuxt> にカスタム ページ キーまたは keep-alive props を渡していた場合、definePageMeta を使用してこれらのオプションを設定できるようになりました。

詳しくは、Nuxt コンポーネントフックの移行 を参照してください。

ページとレイアウトの遷移

ページやレイアウトの遷移をコンポーネントオプションで直接定義していた場合、definePageMeta を使用して遷移を設定する必要があります。

pages/ の詳細についてはこちらをご覧ください。

移行

1. 動的なパラメータを持つページの名前を、新しい形式に合うように変更します。
2. <Nuxt> と <NuxtChild> を <NuxtPage> に更新してください。
3. Composition API を使用している場合は、this.$route と this.$router も useRoute と useRouter というコンポーザブルを使用するように移行してください。

例: 動的なルート

- URL: /users
- Page: /pages/users/index.vue

- URL: /users/some-user-name
- Page: /pages/users/_user.vue
- Usage: params.user

- URL: /users/some-user-name/edit
- Page: /pages/users/_user/edit.vue
- Usage: params.user

- URL: /users/anything-else
- Page: /pages/users/_.vue
- Usage: params.pathMatch

- URL: /users
- Page: /pages/users/index.vue

- URL: /users/some-user-name
- Page: /pages/users/[user].vue
- Usage: params.user

- URL: /users/some-user-name/edit
- Page: /pages/users/[user]/edit.vue
- Usage: params.user

- URL: /users/anything-else
- Page: /pages/users/[...slug].vue
- Usage: params.slug

例: ネストされたルートと definePageMeta

<template>
  <div>
    <NuxtChild keep-alive :keep-alive-props="{ exclude: ['modal'] }" :nuxt-child-key="$route.slug" />
  </div>
</template>

<script>
export default {
  transition: 'page' // or { name: 'page' }
}
</script>

<template>
  <div>
    <NuxtPage />
  </div>
</template>

<script setup>
// このコンパイラマクロは、<script> と <script setup> のどちらでも動作します
definePageMeta({
  // 文字列または計算されたプロパティを渡すこともできます
  key: route => route.slug,
  transition: {
    name: 'page',
  },
  keepAlive: {
    exclude: ['modal']
  },
})
</script>

NuxtLink コンポーネント

ほとんどの構文と機能は、グローバルな NuxtLink コンポーネントと同じです。ショートカットの <NLink> 形式を使用していた場合は、<NuxtLink> を使用するように更新する必要があります。

<NuxtLink> は、外部リンクを含むすべてのリンクのドロップイン置き換えになりました。このコンポーネントの詳細と、これを拡張して独自のリンク・コンポーネントを提供する方法については、ドキュメント を参照してください。

プログラマティックなナビゲーション

Nuxt 2 から Nuxt 3 に移行する場合、ユーザーをプログラム的にナビゲートする方法を更新する必要があります。Nuxt 2 では、this.$router を使用して基礎となる Vue Router にアクセスすることができました。Nuxt 3 では、ルートとパラメータを Vue Router に渡すことができる navigateTo() ユーティリティメソッドを使用することができます。

注意: navigateTo で常に 待ち受ける か、関数から返すことでその結果を連鎖させるようにしてください。

<script>
export default {
  methods: {
    navigate(){
      this.$router.push({
        path: '/search',
        query: {
          name: 'first name',
          type: '1'
        }
      })
    }
  }
}
</script>

<script setup>
const router = useRouter();

function navigate(){
  return navigateTo({
    path: '/search',
    query: {
      name: 'first name',
      type: '1'
    }
  })
}
</script>

コンポーネントオプション

asyncData と fetch コンポーネントのオプション

Nuxt 3 は、API からデータをフェッチする ための新しいオプションを提供します。

アイソモーフィックフェッチ

Nuxt 2 では、@nuxtjs/axios または @nuxt/http を使用してデータをフェッチするか、ポリフィルドのグローバルフェッチのみを使用することができます。

Nuxt 3 では、Fetch API または unjs/ohmyfetch を使用する $fetch メソッドと同じ API を持つグローバルに利用可能な フェッチ メソッドを使用することができます。これには以下のような利点があります:

1. サーバー上で実行されている場合は、直接 API を呼び出す ことを「スマートに」処理し、クライアント上で実行されている場合は、あなたの API をクライアントサイドで呼び出すことを処理することができます。(サードパーティの API を呼び出すことも可能です）。
2. さらに、レスポンスの自動解析やデータの文字列化など、便利な機能も備えています。

直接 API を呼び出したり 、データを取得したりする 方法について詳しく知れます。

コンポーザブルの使用

Nuxt 3 には、データを取得するための新しい複合変数、useAsyncData と useFetch があります。これらにはそれぞれ「遅延」バージョン（useLazyAsyncData と useLazyFetch）があり、クライアントサイドのナビゲーションをブロックしないようにすることができます。

Nuxt 2 では、以下のような構文でコンポーネントのデータをフェッチします:

export default {
  async asyncData({ params, $http }) {
    const post = await $http.$get(`https://api.nuxtjs.dev/posts/${params.id}`)
    return { post }
  },
  // or alternatively
  fetch () {
    this.post = await $http.$get(`https://api.nuxtjs.dev/posts/${params.id}`)
  }
}

メソッドやテンプレートの中で、コンポーネントが提供する他のデータを使用するのと同じように、post 変数を使用することができます。

Nuxt 3 では、setup() メソッドまたは <script setup> タグで composables を使用してこのデータフェッチを行うことができます:

<script setup>
  // Define params wherever, through `defineProps()`, `useRoute()`, etc.
  const { data: post, refresh } = await useAsyncData('post', () => $fetch(`https://api.nuxtjs.dev/posts/${params.id}`) )
  // Or instead - useFetch is a convenience wrapper around useAsyncData when you're just performing a simple fetch
  const { data: post, refresh } = await useFetch(`https://api.nuxtjs.dev/posts/${paramsÌ.id}`)
</script>

Nuxt 3 テンプレート内で post を使用したり、refresh を呼び出してデータを更新することができるようになりました。

マイグレーション

1. page/component 内の asyncData フックを useAsyncData または useFetch に置き換えてください。
2. コンポーネント内の fetch フックを useAsyncData または useFetch に置き換えてください。

head

meta tag migration を参照してください。

key

definePageMeta コンパイラマクロ内でキーを定義できるようになりました。

- <script>
- export default {
-   key: 'index'
-   // or a method
-   // key: route => route.fullPath
- }
+ <script setup>
+ definePageMeta({
+   key: 'index'
+   // or a method
+   // key: route => route.fullPath
+ })
  </script>

移行

1. コンポーネントオプションから definePageMeta に key を移行する。

layout

レイアウトの移行 を参照してください。

loading

この機能は Nuxt 3 ではまだサポートされていません。

middleware

ミドルウェアの移行 を参照してください。

scrollToTop

この機能は Nuxt 3 ではまだサポートされていません。vue-router のデフォルトのスクロール動作を上書きしたい場合は、 ~/app/router.options.ts で上書きできます（詳しくは ドキュメント をご覧ください）。

transition

レイアウトの移行 を参照してください。

validate

Nuxt 3 では validate フックがなくなりました。代わりに、カスタムミドルウェア関数を作成するか、ページの設定関数で直接エラーを投げることができる。

- <script>
- export default {
-   async validate({ params, query, store }) {
-     return true // if valid
-   }
- }
+ <script setup>
+ definePageMeta({
+   middleware: [
+     async function (to, from) {
+       const nuxtApp = useNuxtApp()
+       if (!valid) {
+         return abortNavigation('Page not found')
+       }
+     }
+   ]
+ })
  </script>

watchQuery

これは Nuxt 3 ではサポートされていません。代わりに、データのリフェッチをトリガするために直接ウォッチャーを使用することができます。

<script setup>
const route = useRoute()
const { data, refresh } = await useFetch('/api/user')
watch(() => route.query, () => refresh())
</script>

ランタイム設定

Nuxt 3 アプリ内で環境変数を参照したい場合は、ランタイム設定を使用する必要があります。

コンポーネント内でこれらの変数を参照する場合、セットアップメソッド（または Nuxt プラグイン）内で useRuntimeConfig コンポーザブルを使用する必要があります。アプリの server/ 部分では、インポートなしで useRuntimeConfig を使用することができます。

ランタイム設定についてもっと読む 。

移行

1. アプリで使用する環境変数を nuxt.config ファイルの runtimeConfig プロパティに追加します。
2. アプリの Vue 部分全体で、process.env を useRuntimeConfig に移行します。

例

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  runtimeConfig: {
    secretKey: '', // variable that can only be accessed on the server side
    public: {
      BASE_URL: process.env.BASE_URL || 'https://nuxtjs.org' // variable that can also be accessed on the client side
    }
  },
})

<script setup>
  const config = useRuntimeConfig().public
  // instead of process.env.BASE_URL you will now access config.BASE_URL
</script>

const config = useRuntimeConfig().public

export default (req, res) => {
  // you can now access config.BASE_URL
  return {
    baseURL: config.BASE_URL
  }
}

ビルドツール

デフォルトでは、以下のビルドツールを使用します。

• Vite または webpack
• Rollup
• PostCSS
• esbuild

このため、nuxt.config にある以前のビルド設定のほとんどは、カスタム babel 設定を含めて無視されるようになりました。

もし Nuxt のビルドツールのどれかを設定する必要がある場合は、新しいトップレベルの vite, webpack, postcss キーを使って、nuxt.config で設定することができます。

さらに、Nuxt は TypeScript をサポートしています。詳細はこちら 。

ステップ

1. nuxt/typescript-build と @nuxt/typescript-runtime を依存関係やモジュールから削除します。
2. babel の未使用の依存関係をプロジェクトから削除します。
3. 明示的な core-js の依存関係を削除します。
4. require を import に移行する。

サーバー

ビルドされた Nuxt 3 アプリケーションでは、ランタイムの Nuxt 依存はありません。これは、あなたのサイトが高いパフォーマンスと超スリムになることを意味します。しかし、それは同時にランタイム Nuxt サーバーフックにフックすることができなくなることも意味します。

Nitro サーバーエンジンの詳細については、こちらをご覧ください 。

ステップ

1. nuxt.config にある render キーを削除します。
2. server/api と ~/server/middleware にあるファイルは自動的に登録されるので、serverMiddleware 配列から削除してください。
3. serverMiddleware 配列の他のアイテムは、インライン関数ではなく、ファイルや npm パッケージを直接指定するように更新してください。
4. server: や vue-renderer: などのサーバーフックを追加している場合は、これらを削除して、ランタイムフックやプラグインの nitropack サポートを待つ必要があります。

モジュール

モジュールの互換性

Nuxt 3 は @nuxt/kit 自働ラッパーを使用した Nuxt 2 モジュールの基本的な後方互換性レイヤーを備えています。しかし、通常、モジュールを Nuxt 3 と互換性を持たせるための手順があり、クロスバージョン互換のために Nuxt Bridge の使用が必要な場合もあります。

そこで、@nuxt/kit を用いて Nuxt 3 対応モジュールを作成するための 専用ガイド を作成しました。現在のところ、これに従ってモジュールを書き換えるのが最適な移行方法です。このガイドの残りの部分は、モジュールの全面的な書き換えを避け、Nuxt 3 と互換性のあるモジュールを作成するための準備手順を含んでいます。

プラグインの互換性

Nuxt 3 のプラグインは Nuxt 2 と完全な後方互換性がありません。

Vue との互換性

Composition API を使用するプラグインやコンポーネントは、Vue 2 または Vue 3 を排他的にサポートする必要があります。

vue-demi を使用することで、Nuxt 2 と 3 の両方と互換性があるはずです。

モジュールの移行

Nuxt 3 ユーザーがあなたのモジュールを追加すると、@nuxt/kit から互換性のあるモジュールコンテナレイヤーが 自動的に注入される ので、あなたのコードが以下のガイドラインに従っている限り、そのまま動作し続けるはずです。

nuxt/bridge でテストする

nuxt/bridge への移行は、Nuxt 3 をサポートするための最初の、そして最も重要なステップです。

モジュールにフィクスチャやサンプルがある場合は、@nuxt/bridge パッケージをその設定に追加してください (例 を参照してください)。

CommonJS から ESM への移行

Nuxt 3 は TypeScript と ECMAScript Modules をネイティブにサポートしています。詳細とアップグレードについては、Native ES Modules を参照してください。

プラグインがデフォルトでエクスポートするようにする

Vue のグローバルプラグインなど、export default を持たない Nuxt プラグインを注入する場合は、export default () => { } を末尾に追加することを確認してください。

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

export default () => { }