Nuxt/docs/content/7.bridge/2.migration.md

# Bridge Migration

> ⚠️ This section is work-in-progress and can change. Please regularly check this page.

## ... I have a nuxt2 project

Migration to nuxt-bridge, should be almost straight forward!

**Why migrate:**

- It is risk-free! You can roll back by just commenting out one line in config
- Makes your project almost ready for nuxt3 migration
- Enjoy new DX improvements without major rewrites for vue3
- Use nitro engine for platform agnostic and optimized deployments
- Help us stabilize nuxt3 and discover flows
- Bridge is more stable than nuxt3 at the moment for migration

### **Step 1:** Ensure using latest version of nuxt

Remove package lock file (`package-lock.json` and `yarn.lock`) and update to latest version of nuxt2 ([releases](https://github.com/nuxt/nuxt.js/releases)) or use `nuxt-edge` for latest updates and fixes.

### **Step 2:** Install bridge module

Install `@nuxt/bridge` as a devDependency:

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

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

Update `nuxt.config` file:

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

export default defineNuxtConfig({
  bridge: {
    nitro: true,
    // vite: true
  }
})
```

If you have a project with `target: 'static'`, update "build" script to use `nuxt generate`

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

### **Step 3:** Avoid CommonJS syntax

See [Migrating from CommonJS](#step-2-avoid-commonjs-syntax) from module author section.
We need same steps for `plugins`, `store`, `pages`, `serverMiddleware` and `nuxt.config.js`.

### **Step 4:** Remove incompatible modules

- Remove `@nuxt/content` (1.x): **note**: a v2 rewrite for nuxt 3 support is planned, or you may also use docus
- Remove `nuxt-vite`: Bridge injects module when enabled with `{ bridge: { vite: true } }`
- Remove `@nuxt/nitro`: Bridge injects module
- Remove `@nuxtjs/composition-api`: Bridge provides a nuxt 3 compatible composition-api layer.

### **Step 5:** Ensure everything goes well

Try with both `nuxt dev`, `nuxt build` and `nuxt start` if everything goes as expected
If there is an issue, please report it to us or to relevant module repository.

If you cannot take the risk of using experimental code, you can comment out the module and regularly check back to ensure your project stays ready for nuxt3 compatibly.

### 🥳 Enjoy new possibilities!

Everything goes well? Congratulations! You are welcome to enjoy new features from nuxt3 without full migration. See table in intro section for more.

## ... I am a module author

When users of nuxt3 use your module, a compatible module container layer from `@nuxt/kit` is automatically injected
so as long as your code is following below guidelines, it should continue working as is.

### **Step 1:** Test it with `@nuxt/bridge`:

Migrating to `@nuxt/bridge` is the first and most important step for supporting nuxt3.

If you have a fixture in your module, add `@nuxt/bridge` package to its config (same steps as previous section for nuxt2 projects)

### **Step 2:** 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 3:** Ensure plugins have default export

If you inject a nuxt plugin that does not have `export default` (such as global Vue plugins), ensure you add `export default {}` to the end of it

### **Step 4:** Avoid runtime modules

With nuxt3 and nitro project, we started to rethink how the nuxt build process should work and modules hooking into the Nuxt runtime is now considered an anti-pattern and will not work with nuxt3.

Your module should work fine by adding only to `buildModules[]` (instead of `modules[]`):

- Avoid updating `process.env` within nuxt module and reading by a nuxt plugin. Use `runtimeConfig` instead
- (*) Avoid depending on runtime hooks like `vue-renderer:*` for production
- (*) Avoid adding `serverMiddleware` by importing them inside module. Add them by referencing to file path so that they are independent of module context

(*) Unless it is for `nuxt dev` purpose only and guarded with `if (nuxt.options.dev) { }`.

### **Step 5**: Add module meta

Ensure your module is exporting meta object.

[TODO]

### **Step 6:** Migrate to TypeScript (optional)

While it is not essential, most of nuxt ecosystem is shifting to use TypeScript, it is highly recommended to consider migration.

**Tip:** You can start migration by simply renaming `.js` files, to `.ts`. TypeScript is designed to be progressive!

**Tip:** You can use TypeScript syntax for nuxt 2/3 modules and plugins without any extra dependencies.

### 🛣️ Next Steps

While we are evolving nuxt3 and modules, you are welcome to share any ideas in Discussions section.

A brand new experience of defining nuxt modules is coming with `@nuxt/kit` project but it is still not ready so it is advised only to try it and not release to stable versions of your module.

Please regularly check this section for latest updates.