# Nuxt Bridge

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

Nuxt3 brings a brand-new experience for developing Vue applications.

To make this happen, we've rewritten most parts of nuxt codebase and are using the latest tooling such as Webpack5, Vite, vue3 and native ESM.
And we've also rethought how nuxt rendering works by introducing the `@nuxt/nitro` project.

Our goal is a smooth transition path from legacy stack to new one, reducing breaking changes as much as possible.

To make this happen, we considered backward- and forward-compatibility and most layers (such as modules and plugins). Nonetheless, this is in progress and a bumpy road.

In the meantime, you can make sure your project is almost ready for nuxt3 and have the latest DX experience without major rewrites and risk of breaking changes by adding a simple module.

👉 Please see [Migration Guide](./migration) for more details on how you can migrate your nuxt 2 project or module to bridge level.

## Nuxt 2 vs Nuxt Bridge vs Nuxt 3

In the table below, there is a quick comparison between 3 versions of nuxt:

Feature / Version        | Nuxt 2          | Nuxt Bridge      | Nuxt 3
-------------------------|-----------------|------------------|---------
Stability                | 😸 Stable      | 😺 Semi Stable   | 🙀 Unstable
Performance              | 👎 Slower      | 👍  Enhanced     | 🔥 Fastest
Nitro Engine             | ❌             | ✅               | ✅
ESM support              | 🌙 Partial     | 👍 Better        | ✅
TypeScript               | ☑️ Opt-in      | 🚧 Faster        | ✅
Composition API          | ⚠️ Deprecated  | ✅               | ✅
Components Auto Import   | ✅             | ✅               | ✅
`<script setup>` syntax  | ❌             | 🚧 Partial       | ✅
Auto Imports             | ❌             | ✅               | ✅
Webpack                  | 4              | 4                | 5
Vite                     | ⚠️ Partial     | 🚧 Partial       | 🚧 Experimental
Nuxi CLI                 | ❌ Old         | ✅               | ✅

## Nuxt 3 vs Nuxt 2

The good news is that most features from Nitro Engine and the new CLI, like `api` routes, will be supported when you use `@nuxt/bridge`.

Some features have been dropped from nuxt2, some still need to be implemented for nuxt3 and some are new in nuxt3.
Biggest changes with nuxt3 other than the ones covered by bridge, are `vue2` to `vue3`, webpack5 and Core rewrite with new templating engine.

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.

In table below there is an overall feature comparation table (might be incomplete or outdated):


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 (see [migration](./migration)) or if they are already following guidelines
- All (upcoming) modules made with `@nuxt/kit` should be backward compatible with nuxt2  projects (even without bridge) as long as they are not depending on a nuxt3/bridge-only feature

### Nuxt Plugin Compatibility

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

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