# Migration

Nuxt 3 migration guide (Work in progress)

## ⬆️ Nuxt 2 to Nuxt 3

At the moment, there is no Nuxt 2 to Nuxt 3 migration guide nor is recommanded to do it due to potentially more changes coming.
We are working to provide a stable migration guide and tooling to make it as smooth as possible. Please check [Bridge](/getting-started/bridge) for the alternative.

Some features have been dropped from Nuxt 2, some yet need to be implemented for Nuxt 3 and some are new in Nuxt 3 (and Bridge).

Noticable and/or Breaking changes with Nuxt 3 other than the requirements of bridge are:

- Vue app templates are rewritten
- Vue upgraded to `3.x`
- Using suspense for async data fetching
- Webpack `5.x` (if not using `vite`)
- Components discovery is rewritten
- Introduced new `App.vue`
- Introduced new `layouts`
- `pages/` directory conventions changed

In table below there is an overall feature comparation table:

Feature / Version         | Nuxt 2  | Nuxt 3   | Changes required
--------------------------|---------|----------|------------------
Vue Version               | 2       | 3        | Yes
`app.vue`                 | ❌      | ✅        | -
Assets                    | ✅      | ✅        | No
Components                | ✅      | ✅        | No
Layouts                   | ✅      | ✅        | Yes
Error Pages               | ✅      | 🚧        | Yes
Pages                     | ✅      | ✅        | Yes
Pages: Dynamic Params     | ✅      | ✅        | Yes
Pages: _.vue              | ✅      | ✅        | No
Plugins                   | ✅      | ✅        | Yes (compatible by default)
Store                     | ✅      | 🚧        | Yes
Transitions               | ✅      | 🚧        | ?
Suspense                  | ❌      | ✅        | -
Options API: `asyncData`  | ✅      | 🚧        | ?
Options API: `fetch`      | ✅      | 🚧        | ?


### Nuxt Module Compatibility

- All Nuxt 2 modules should be forward compatible with Nuxt 3 as long as they migrate to bridge or if they are already following guidelines
- All (upcoming) modules made with `@nuxt/kit` should be backward compatible with Nuxt 2  projects (even without bridge) as long as they are not depending on a nuxt3/bridge-only feature

### Nuxt Plugin Compatibility

- Most Nuxt 2 plugins should be forward compatible with nuxt3 with a magical compat layer we inject
- Nuxt3 plugins are **not** backward compatible with Nuxt 2

### Vue Compatibility

For plugins and composition API and components, it needs exclusive vue2 or vue3 support from plugins.
By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatible with both nuxt2 and nuxt3.

## 📦 Module Migration Guide

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.

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

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

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

### 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) { }`.

### Add module meta

Ensure your module is exporting meta object.

[TODO]

### 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.