Nuxt/docs/content/7.bridge/1.intro.md

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 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) 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 they should be compatible with both nuxt2 and nuxt3.