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](/getting-started/installation).<br>
Learn more in [Introduction](/getting-started/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`:

```diff [package.json]
- "nuxt": "^2.15.0"
+ "nuxt-edge": "latest"
```

Then, reinstall your dependencies:

::code-group

```bash [Yarn]
yarn install
```

```bash [NPM]
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

```bash [Yarn]
yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge
```

```bash [NPM]
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`](/getting-started/commands/). Update your scripts as follows to leverage the better support from Nuxt Bridge:

```diff
{
  "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`.

```json [package.json]
{
  "scripts": {
    "build": "nuxi generate"
  }
}
```

### Server target

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

```json [package.json]
{
  "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.

```ts [nuxt.config.js|ts]
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:

```diff [tsconfig.json]
{
+ "extends": "./.nuxt/tsconfig.json",
  "compilerOptions": {
    ...
  }
}
```

## Avoid CommonJS syntax

Nuxt 3 natively supports TypeScript and ECMAScript Modules.

### Update the imports

::code-group

```js [Before]
const lib = require('lib')
```

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

::

### Update the exports

::code-group

```js [Before]
module.exports = ...
```

```js [After]
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 the bridge in the meantime:

```ts [nuxt.config.js|ts]
import { defineNuxtConfig } from '@nuxt/bridge'

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

## Feature Flags

You can optionally disable some features from bridge or opt-in to less stable ones. In normal circumstances, it is always best to stick with defaults!

You can check [bridge/src/module.ts](https://github.com/nuxt/framework/blob/main/packages/bridge/src/module.ts) for latest defaults.

```ts [nuxt.config.js|ts]
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {

    // -- Opt-in features --

    // Use Vite as the bundler instead of Webpack 4
    // vite: true,

    // -- Default features --

    // Use legacy server instead of Nitro
    // nitro: false,

    // Disable nuxt 3 compatible `nuxtApp` interface
    // app: false,

    // Disable composition API support
    // capi: false,

    // Do not transpile modules
    // transpile: false,

    // Disable <script setup> support
    // scriptSetup: false,

    // Disable composables auto importing
    // autoImports: false,

    // Do not warn about module incompatibilities
    // constraints: false,

    // Disable Nuxt 3 compatible useMeta
    // meta: false,
  },

  vite: {
    // Config for Vite
  }
})
```