3.0 KiB

Raw Blame History

Bridge

Experience Nuxt 3 features on existing Nuxt 2 projects.

::alert If you're starting a fresh Nuxt 3 project, please skip this section and go to Nuxt 3 Installation.
Learn more in Introduction. ::

Bridge is a forward-compatibility layer that allows you to experience many of new Nuxt 3 features by simply installing and enabling a Nuxt module.

Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 and have the best developer experience without needing a major rewrite or risk breaking changes.

Upgrade Nuxt 2

Remove any package lockfiles (package-lock.json and yarn.lock) and use the latest nuxt-edge:

package.json

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

Then, reinstall your dependencies:

::code-group

yarn install

npm install

::alert Once the installation is complete, make sure both development and production builds are working as expected before proceeding. ::

Install Nuxt Bridge

Install @nuxt/bridge-edge as a development dependency:

::code-group

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

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

Update `nuxt.config`

Please make sure to avoid any CommonJS syntax such as module.exports, require or require.resolve in your config file. It will soon be deprecated and unsupported.

You can use static import, dynamic import() and export default instead. Using TypeScript by renaming to nuxt.config.ts is also possible and recommended.

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  // Your existing configuration
})

Avoid CommonJS syntax

Nuxt 3 natively supports TypeScript and ECMAScript modules.

In every file make sure to:

Change require('lib') to import lib from 'lib' or await import('lib').then(e => e.default || e)
Change module.exports to export default or export const
Avoid usage of __dirname and __filename as much as possible

Remove incompatible and obsolete modules

Remove @nuxt/content (1.x) a v2 rewrite for nuxt 3 support is planned, or you may also use docus
Remove nuxt-vite: Bridge enables same functionality
Remove @nuxtjs/typescript-build: Bridge enables same functionality
Remove @nuxtjs/typescript-runtime and nuxt-ts: Nuxt 2 has built-in runtime support
Remove @nuxt/nitro: Bridge injects same functionality
Remove @nuxtjs/composition-api: Bridge provides a Nuxt 3 compatible composition-api layer and help to remove dependency

Ensure everything goes well

✔️ Try with nuxt dev and nuxt build (or nuxt generate) to see if everything goes well.

🐛 Is something wrong? Please let us know by creating an issue. Also, you can easily disable bridge in the meantime:

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: false // Temporarily disable bridge integration
})

3.0 KiB Raw Blame History