Nuxt Bridge

以前Nuxt3での変更点についての記事を書きました。

あれから5ヶ月以上が経過し、先日遂にNuxt3が正式リリースされました

担当しているプロダクトでVue3及びNuxt3へのアップデート対応を行う話も進んできました。

Nuxt2からNuxt3への移行ツールとして公式からNuxt Bridgeというものが提供されています。

今回はこのNuxt Bridgeについて書いていきます。

Nuxt Bridgeとは

前述の通り、Nuxt BridgeはNuxt公式が提供している移行ツールです。

Nuxt公式サイトに各バージョンごとの機能を比較した表も用意されています。

Nuxtのバージョンごとの比較

これを見ると、

  • パフォーマンスはより速く
  • Nitro Engineの採用
  • ESM (ECMAScript Modules)のサポート強化
  • TypeScript, Composition API, Viteへの一部対応
  • Auto Imports対応
  • Nuxi CLI対応

等の点でNuxt2より勝っているようです。

Nuxt Bridgeへの移行

移行方法も公式が全部まとめてくれています

Nuxt2をアップグレード

package-lock.jsonを削除してpackage.jsonを以下のように変更します。

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

Nuxt Bridgeをインストール

上記が完了したらNuxt Bridgeをインストールします。

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

Nuxiコマンドに更新

Nuxt2ではnuxtコマンドを使用していましたが、Nuxt Bridge及びNuxt3ではnuxiコマンドに変わりました。

なので再びpackage.jsonを更新します。

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

nuxt.configを更新

requiremodule.exports等のCommonJS形式の記法は将来的にサポートされなくなるため、それらを使用している箇所はそれぞれimportexport defaultに修正します。

nuxt.config.js(ts)を以下のように修正します。

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  // 設定を記載
})

tsconfig.jsonを更新

TypeScriptを使う場合はtsconfig.jsonを以下のように修正して、Nuxtが自動生成するtsconfig.jsonをマージします。

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

ランタイム設定

環境変数を使用したい場合は以下のように設定します。

// nuxt.config.js
runtimeConfig: {
  apiKey: process.env.NUXT_API_KEY, // サーバーサイドでのみ参照可能
  public: {
    BASE_URL: process.env.BASE_URL // サーバーサイド・クライアントサイド両方で参照可能
  }
}
<template>
<div>Website: {{ $config.public.BASE_URL }}</div>
</template>

<script setup>
  const config = useRuntimeConfig().public
  console.log(config.BASE_URL)
</script>

Composition APIへの移行

こちらにまとめられているのでご参照ください。

互換性のない、または古いモジュールの削除

以下のモジュールを削除します。

  • @nuxt/content (1.x)
    • 2.xでNuxt3に対応しました
  • nuxt-vite
  • @nuxt/typescript-build
  • @nuxt/typescript-runtime
  • nuxt-ts
  • @nuxt/nitro
  • @vue/composition-api
  • @nuxtjs/composition-api

.gitignoreに追記

.output.gitignoreに追加します。

プラグインの修正

プラグインの設定方法がNuxt2から変わったので以下のように修正します。

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.provide('injected', () => 'my injected function')
  // `nuxtApp.$injected`で使えるようになります
})

メタ情報の設定

Nuxt2ではheadオプションでメタ情報を設定できましたが、Nuxt3ではuseHeadを使います。

<script setup>
useHead({
  title: 'My Nuxt App',
})
</script>

Feature Flags

Nuxt Bridgeではいくつかの機能を無効にしたりすることができます。

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 用の設定
  }
})

まとめ

以上、Nuxt Bridgeについて簡単にまとめてみました。

実際の移行作業はそう簡単には進まないと思いますが、根気よく対応していきたいと思います。