Nuxt/docs/content/1.getting-started/5.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 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 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 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.