Nuxt/docs/content/1.getting-started/6.migration.md

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 it recommended 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 for the alternative.

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

Noticeable and/or breaking changes for Nuxt 3 other than the requirements of Nuxt Bridge are:

::list{type=warning}

• 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 main app.vue component
• Introduced new layouts system
• The pages/ directory conventions changed ::

The below table highlights an overall feature comparison:

Feature / Version	Nuxt 2	Nuxt 3	Changes required	More information
Vue Version	2	3	Yes
app.vue	❌	✅	-
Suspense	❌	✅	-
Assets	✅	✅	No
Components	✅	✅	No
Layouts	✅	✅	Yes
Middleware	✅	✅	Yes
Pages	✅	✅	Yes
Pages: Dynamic Params	✅	✅	Yes
Pages: _.vue	✅	✅	Yes (new naming system)
Plugins	✅	✅	Yes (compatible by default)
Transitions	✅	✅	?
Options API: asyncData	✅	✅	Yes (use defineNuxtComponent)
Options API: fetch	✅	❌	Use asyncData instead
Error Pages	✅	🚧	Yes	Handling runtime errors
Store	✅	🚧	Yes	Global store support
Static builds	✅	🚧		Route Caching rules (Hybrid)

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 Nuxt 3 / Bridge-only feature.

Plugin Compatibility

Most Nuxt 2 plugins should be forward compatible with Nuxt 3 with a magical compat layer we inject.

Nuxt 3 plugins are not backward compatible with Nuxt 2.

Vue Compatibility

For plugins using composition API or components, it needs exclusive Vue 2 or Vue 3 support.

By using vue-demi they should be compatible with both Nuxt 2 and 3.

Module Migration

When Nuxt 3 users add your module, a compatible module container layer from @nuxt/kit is automatically injected, so as long as your code is following the guidelines below, it should continue working as-is.

Test with @nuxt/bridge

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

If you have a fixture or example in your module, add @nuxt/bridge package to its config (see example)

Migrate from CommonJS to ESM

Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check Native ES Modules for more info and upgrading.

Ensure plugins 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.

::code-group

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

export default () => { }

::

Avoid runtime modules

With Nuxt 3, Nuxt is now a build-time-only dependency, which means that modules shouldn't attempt to hook into the Nuxt runtime.

Your module should work even if it's only added to buildModules (instead of modules). For example:

• Avoid updating process.env within a 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 the module. Instead, add them by referencing a file path so that they are independent of the module's context

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

::alert{type=info icon=🔎} Continue reading about Nuxt 3 modules in the Modules guide. ::

Use TypeScript (optional)

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

::alert{icon=💡} You can start migration by renaming .js files, to .ts. TypeScript is designed to be progressive! ::

::alert{icon=💡} You can use TypeScript syntax for Nuxt 2 and 3 modules and plugins without any extra dependencies. ::