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

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 lock files (package-lock.json and yarn.lock) and use the latest nuxt-edge:

- "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

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

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

::

Update your scripts

You will also need to update your scripts within your package.json to reflect the fact that Nuxt will now produce a Nitro server as build output.

Nuxi

Nuxt 3 introduced the new Nuxt CLI command nuxi. Update your scripts as follows to leverage the better support from Nuxt Bridge:

{
  "scripts": {
-   "dev": "nuxt",
+   "dev": "nuxi dev",
-   "build": "nuxt build",
+   "build": "nuxi build",
-   "start": "nuxt start",
+   "start": "node .output/server/index.mjs"
  }
}

Static target

If you have set target: 'static' in your nuxt.config then you need to ensure that you update your build script to be nuxi generate.

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

Server target

For all other situations, you can use the nuxi build command.

{
  "scripts": {
    "build": "nuxi build",
    "start": "node .output/server/index.mjs"
  }
}

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
})

Update tsconfig.json

If you are using TypeScript, you can edit your tsconfig.json to benefit from auto-generated Nuxt types:

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

Avoid CommonJS syntax

Nuxt 3 natively supports TypeScript and ECMAScript Modules.

Update the imports

::code-group

const lib = require('lib')

import lib from 'lib'
// or using code-splitting
const lib = await import('lib').then(e => e.default || e)

::

Update the exports

::code-group

module.exports = ...

export default ...
// or using named export
export const hello = ...

::

Avoid using specific CJS syntax

Avoid the usage of __dirname and __filename as much as possible.

Remove incompatible and obsolete modules

• Remove @nuxt/content (1.x). A rewrite for nuxt 3 is planned (2.x)
• Remove nuxt-vite: Bridge enables same functionality
• Remove @nuxt/typescript-build: Bridge enables same functionality
• Remove @nuxt/typescript-runtime and nuxt-ts: Nuxt 2 has built-in runtime support
• Remove @nuxt/nitro: Bridge injects same functionality
• Remove @nuxtjs/composition-api from your dependencies (and from your modules in nuxt.config). Bridge provides a legacy composition API layer that handles imports within your files from @nuxtjs/composition-api until you've fully finished migrating to native Bridge/Nuxt 3 composables (which you will import from by #app, or via auto-imports).

Exclude Nuxt build folder from git

Add the folder .output to the .gitignore file.

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
})