Nuxt/docs/content/1.getting-started/3.bridge.md

Bridge

Experience Nuxt 3 on existing Nuxt 2 projects

Please skip this section if starting a new Nuxt 3 project and go to Installation instead. Learn more in the Intorduction.

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 latest DX experience without major rewrites and risk of breaking changes by adding a simple module.

Step 1: Upgrade to the latest version of 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"

✔️ After upgrade, please make sure both development and production builds are working fine before proceed to the module installation.

Step 2: Install bridge module

Install @nuxt/bridge-edge as a devDependency:

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

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

Step 3: 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
})

Step 4: Avoid CommonJS syntax

Nuxt 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

Step 5: 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

Step 6: 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
})