migration/modules

15 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Nuxt 3 has backward compatibility layer for Nuxt 2 modules

Nuxt 3 includes a basic backward compatibility layer for Nuxt 2 modules using @nuxt/kit auto wrappers. However, there are usually migration steps required to make modules fully compatible with Nuxt 3, and sometimes using Nuxt Bridge is required for cross-version compatibility.

Recommended migration path for Nuxt 2 modules to Nuxt 3

The recommended migration path is to follow the Dedicated Guide for authoring Nuxt 3 ready modules using @nuxt/kit and rewrite your modules. This is considered the best approach rather than making minimal compatibility changes.

Nuxt 3 plugins are not fully backward compatible with Nuxt 2

Nuxt 3 plugins are not fully backward compatible with Nuxt 2 plugins and require migration.

Use vue-demi for Composition API compatibility across Nuxt 2 and 3

Plugins or components using the Composition API need exclusive Vue 2 or Vue 3 support. By using vue-demi, they should be compatible with both Nuxt 2 and 3.

Module container is not accessible in Nuxt 3

When Nuxt 3 users add your module, you will not have access to the module container (this.*), so you must use utilities from @nuxt/kit to access the container functionality.

Test module migration with @nuxt/bridge first

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.

Migrate Nuxt modules from CommonJS to ESM

Nuxt 3 natively supports TypeScript and ECMAScript Modules. Modules should be migrated from CommonJS to ESM.

Add default export to Nuxt plugins

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.

Plugin default export example for global Vue plugins

Example of adding default export to a global Vue plugin: ```js // ~/plugins/vuelidate.js import Vue from 'vue' import Vuelidate from 'vuelidate' Vue.use(Vuelidate) export default () => { } ```

Avoid runtime modules in Nuxt 3

With Nuxt 3, Nuxt is now a build-time-only dependency, which means that modules should not attempt to hook into the Nuxt runtime. A module should work even if it is only added to buildModules instead of modules.

Do not update process.env in Nuxt 3 modules

Avoid updating process.env within a Nuxt module and reading it by a Nuxt plugin. Use runtimeConfig instead.

Avoid runtime hooks in Nuxt 3 modules for production

Avoid depending on runtime hooks like vue-renderer:* for production in Nuxt 3 modules. This only applies if the usage is for nuxt dev purpose only and is guarded with if (nuxt.options.dev) { }.

Do not import serverMiddleware directly in Nuxt 3 modules

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. This only applies if the usage is for nuxt dev purpose only and is guarded with if (nuxt.options.dev) { }.

Use TypeScript for Nuxt modules (optional)

While not essential, most of the Nuxt ecosystem is shifting to use TypeScript, and it is highly recommended to consider migration. You can start migration by renaming .js files to .ts. TypeScript is designed to be progressive and you can use TypeScript syntax for Nuxt 2 and 3 modules and plugins without any extra dependencies.

Remove @nuxt/components from Nuxt 2 migration

When migrating from Nuxt 2, if you were using @nuxt/components, you can remove 'components: true' from your nuxt.config. If you had a more complex setup, note that component options have changed, and you should refer to the components documentation.

Give your agent this brain