3.0 KiB

Raw Blame History

Bridge

Experience Nuxt 3 features on existing Nuxt 2 projects.

::alert Please skip this section if starting a fresh Nuxt 3 project and go to Installation.
Learn more in Introduction. ::

Bridge is a forward-compatibility layer as a module that allows you to opt-in and experience many of new Nuxt 3 features.

Using bridge, you can make sure your project is almost ready for Nuxt 3 and have the best developer experience without major rewrites and risk of breaking changes.

Upgrade Nuxt 2

Remove package lock-file (package-lock.json and yarn.lock) and use latest nuxt-edge:

package.json

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

Then, install again the dependencies:

::code-group

yarn install

npm install

::alert Once the installation is done, make sure both development and production builds are working fine before proceed to the module installation. ::

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 config file. It will be soon 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.

🐛 Something is wrong? Please report us by creating an issue. Also, you can easily disable bridge in the meantime:

import { defineNuxtConfig } from '@nuxt/bridge'

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

3.0 KiB Raw Blame History