reactivityTransform migration from Vue 3.4 and Nuxt 3.9
Since Nuxt 3.9 and Vue 3.4, reactivityTransform has been moved from Vue to Vue Macros which has a Nuxt integration.
Nuxt · Getting started · all subjects
migration from nuxt 2
60 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Remove components config 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 complex setup, note that component options have changed, so refer to the components documentation for more information.
Migrate router.extendRoutes to pages:extend hook
In Nuxt 3, replace router.extendRoutes with the pages:extend hook in the hooks object. The pages:extend hook receives routes as a parameter and is defined within defineNuxtConfig({ hooks: { 'pages:extend' (routes) { } } }).
Migrate router.routeNameSplitter using pages:extend hook
In Nuxt 3, achieve router.routeNameSplitter functionality by implementing custom route name generation logic in the pages:extend hook. Use createResolver from @nuxt/kit to resolve the pages directory path, then iterate through routes and update their names based on file paths using the desired separator.
Nuxt 3 is ESM native
Nuxt 3 is an ESM native framework. In nuxt.config files, avoid using require and module.exports. Instead, use export default for exports and import statements for dependencies. Although unjs/jiti provides semi-compatibility, ESM syntax is the recommended approach.
Async configuration is deprecated in Nuxt 3
Async config syntax is deprecated in Nuxt 3 to make Nuxt loading behavior more predictable. For async operations, use Nuxt hooks instead.
buildModules moved to modules in Nuxt 3
In Nuxt 3, all buildModules should be moved into the modules array. Nuxt and Nuxt modules are now build-time-only.
Update local module paths to entry files in Nuxt 3
If you have local modules pointing to a directory in Nuxt 3, update the module path to point to the entry file. For example, change '~/modules/my-module' to '~/modules/my-module/index'.
static/ directory renamed to public/ in Nuxt 3
The static/ directory for storing static assets has been renamed to public/ in Nuxt 3. You can rename your static directory to public, or keep the old name by setting dir.public in nuxt.config.
Migrate from Vuex to Pinia in Nuxt 3
Nuxt no longer provides Vuex integration. The official Vue recommendation is to use Pinia, which has built-in Nuxt support via the @pinia/nuxt module. If you want to keep using Vuex, manually migrate to Vuex 4 or use the community module nuxt3-vuex-module.
Vue 3 migration guide resources
Read the Vue 3 migration guide at https://v3-migration.vuejs.org and particularly the breaking changes list at https://v3-migration.vuejs.org/breaking-changes/ when migrating to Nuxt 3.
Vue 3 migration build not compatible with Nuxt 3
The Vue 3 migration build from https://v3-migration.vuejs.org/migration-build.html is not currently compatible with Nuxt 3.
Manually migrate Vuex to Vuex 4 in Nuxt 3
If you want to keep using Vuex in Nuxt 3, manually migrate to Vuex 4 following the steps at https://vuex.vuejs.org/guide/migrating-to-4-0-from-3-x.html, then add a plugin file at app/plugins/vuex.ts that imports the store and registers it with nuxtApp.vueApp.use(store).
nuxt3-vuex-module community alternative
For larger apps where updating Vuex creates roadblocks, the community module nuxt3-vuex-module (https://github.com/vedmant/nuxt3-vuex#nuxt3-vuex-module) can be used as it should work out of the box.
defineNuxtConfig function in Nuxt 3
In Nuxt 3, use the defineNuxtConfig function to define your nuxt.config file instead of exporting a plain object. This provides a typed configuration schema. Replace 'export default { }' with 'export default defineNuxtConfig({ })'.
Nuxt 3 backward compatibility for Nuxt 2 modules
Nuxt 3 has a basic backward compatibility layer for Nuxt 2 modules using @nuxt/kit auto wrappers. However, there are usually steps to follow to make modules compatible with Nuxt 3, and sometimes using Nuxt Bridge is required for cross-version compatibility.
Nuxt 3 plugins not fully backward compatible with Nuxt 2
Nuxt 3 plugins are not fully backward compatible with Nuxt 2.
Composition API and Vue version compatibility
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.
No module container access in Nuxt 3
When Nuxt 3 users add a module, you will not have access to the module container (this.*), so you will need to use utilities from @nuxt/kit to access the container functionality.
Test module 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 modules from CommonJS to ESM
Nuxt 3 natively supports TypeScript and ECMAScript Modules. Modules should be migrated from CommonJS to ESM for Nuxt 3 compatibility.
Ensure plugins have default export in Nuxt 3
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.
Nuxt 3 modules should avoid runtime hooks
With Nuxt 3, Nuxt is now a build-time-only dependency. Modules should work even if added only to buildModules instead of modules. Avoid depending on runtime hooks like vue-renderer:* for production, unless it is for nuxt dev purpose only and guarded with if (nuxt.options.dev) { }.
Use runtimeConfig instead of process.env in modules
Avoid updating process.env within a Nuxt module and reading by a Nuxt plugin. Use runtimeConfig instead.
Add serverMiddleware by file path reference, not import
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) { }.
Consider migrating modules to TypeScript
While not essential, most of the Nuxt ecosystem is shifting to use TypeScript, so it is highly recommended to consider migration. 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 render key from nuxt.config in Nuxt 3
When migrating from Nuxt 2 to Nuxt 3, remove the render key from your nuxt.config file as part of the server migration process.
Server files auto-registered in Nuxt 3
In Nuxt 3, any files in ~/server/api and ~/server/middleware are automatically registered. You can remove them from the serverMiddleware array in your configuration.
ServerMiddleware array update for Nuxt 3
When migrating to Nuxt 3, update any remaining items in the serverMiddleware array to point to files or npm packages directly, rather than using inline functions.
No runtime Nuxt dependency in built Nuxt 3 apps
In a built Nuxt 3 application, there is no runtime Nuxt dependency. This means the site will be highly performant and ultra-slim, but you can no longer hook into runtime Nuxt server hooks.
Migrating from process.env to useRuntimeConfig
Replace all process.env references with useRuntimeConfig throughout the Vue part of your app when migrating from Nuxt 2 to Nuxt 3.
Nuxt 2 to Nuxt 3 plugin migration steps
To migrate plugins: (1) Use the defineNuxtPlugin helper function. (2) Remove entries from the nuxt.config plugins array for files in app/plugins/ since they are auto-registered. (3) Use .client.ts or .server.ts filename suffixes instead of the mode property.
Nuxt 2 to Nuxt 3 route middleware migration steps
To migrate route middleware: (1) Use the defineNuxtRouteMiddleware helper function. (2) Change the middleware definition to accept (to, from) parameters. (3) Replace redirect() calls with navigateTo(). (4) Use definePageMeta to specify middleware on components. (5) Place global middleware in ~/middleware with .global extension.
Nuxt Bridge allows Nuxt 2 apps to use Nuxt 3 features
If you need to remain on Nuxt 2 but want to benefit from Nuxt 3 features, you can use Nuxt Bridge as an alternative approach.
Nuxt 3 moves from Vue 2 to Vue 3 with Composition API
Nuxt 3 moves from Vue 2 to Vue 3 and defaults to the Composition API with script setup.
Nuxt 3 is a complete rewrite with significant changes
Nuxt 3 is a complete rewrite of Nuxt 2, built on a new set of underlying technologies. Migration from Nuxt 2 to Nuxt 3 involves significant changes, though migration is expected to become more straightforward as the project moves toward a stable release.
Nuxt 3 uses minimal standalone server compiled with Nitropack
Nuxt 3 moves from a runtime Nuxt dependency to a minimal, standalone server compiled with Nitropack.
Nuxt 3 moves from webpack 4 and Babel to Vite or webpack 5 and esbuild
Nuxt 3 moves from webpack 4 and Babel to either Vite or webpack 5, and uses esbuild instead of Babel.
Migration steps from Nuxt 2 build tooling
To migrate from Nuxt 2 to Nuxt 3 build tooling: (1) Remove @nuxt/typescript-build and @nuxt/typescript-runtime from dependencies and modules. (2) Remove any unused babel dependencies. (3) Remove any explicit core-js dependencies. (4) Migrate require statements to import statements.
Babel configuration no longer used in Nuxt 3
Any custom babel configuration from Nuxt 2 will be ignored in Nuxt 3.
Migration: nuxt.config head to meta
In Nuxt 3, rename the 'head' key to 'meta' in nuxt.config. Consider moving shared meta configuration into app.vue instead. Objects no longer have an 'hid' key for deduplication.
Migration path for Nuxt 2 head() to Nuxt 3
If you need to access component state with the head property in Nuxt 2, migrate to using the useHead composable in Nuxt 3. Alternatively, consider using built-in meta-components.
key option definePageMeta example
definePageMeta({ key: 'index' // or a method // key: route => route.fullPath }) This shows how to set the key option using definePageMeta in Nuxt 3.
asyncData hook migration to useAsyncData composable
In Nuxt 2, the asyncData hook was used to fetch data. In Nuxt 3, replace asyncData with the useAsyncData composable or useFetch composable in your page or component. The useAsyncData composable is more customizable and can do more than simply fetching data from an endpoint.
fetch hook migration to useAsyncData or useFetch
In Nuxt 2, the fetch hook was used in components. In Nuxt 3, replace the fetch hook with useAsyncData or useFetch composable in your component.
key option migration to definePageMeta
In Nuxt 3, the key option is defined within the definePageMeta compiler macro instead of the export default object. It can be a string or a method that receives the route and returns the key.
scrollToTop option migration to definePageMeta
In Nuxt 3, the scrollToTop option is specified within the definePageMeta compiler macro. This feature is not yet fully supported, but you can override the default scroll behavior using router.options.ts.
scrollToTop option definePageMeta example
definePageMeta({ scrollToTop: false }) This shows how to set the scrollToTop option using definePageMeta in Nuxt 3.
validate hook in Nuxt 3
The validate hook in Nuxt 3 accepts a single argument, the route. It can return a boolean value: if false and no other match is found, it results in a 404. Alternatively, you can directly return an object with status and statusText properties to respond immediately with an error.
validate hook definePageMeta example
definePageMeta({ validate: async (route) => { const nuxtApp = useNuxtApp() return /^\d+$/.test(route.params.id) } }) This shows how to use the validate hook with definePageMeta in Nuxt 3, accepting the route argument.
watchQuery not supported in Nuxt 3
The watchQuery option from Nuxt 2 is not supported in Nuxt 3. Instead, you can use a watcher to directly watch route.query changes and trigger refetching data.
watchQuery replacement with watcher example
const route = useRoute() const { data, refresh } = await useFetch('/api/user') watch(() => route.query, () => refresh()) This shows how to replace watchQuery functionality in Nuxt 3 by using a watcher on route.query and calling refresh to refetch data.
loading feature not supported in Nuxt 3
The loading component option from Nuxt 2 is not yet supported in Nuxt 3.
Test Nuxt 5 with future.compatibilityVersion
Set `future.compatibilityVersion: 5` in nuxt.config.ts to test many of Nuxt 5's breaking changes from Nuxt 4.2+. This opts in to Nuxt v5 behavior for multiple features including Vite Environment API, case-sensitive routing, normalized page names, clearNuxtState defaults, non-async callHook, client-only comment placeholders, stricter side-effect imports, Vue Options API disabled, typed pages, and TypeScript baseUrl ignored.
Replace process.* checks with import.meta.*
In Nuxt 5, use `import.meta.*` instead of `process.*` flags. Replace `process.server` with `import.meta.server`, `process.client` with `import.meta.client`, `process.dev` with `import.meta.dev`, `process.test` with `import.meta.test`, and `process.browser` with `import.meta.browser`. The `nuxt/prefer-import-meta` ESLint rule flags remaining `process.*` usage.
jiti no longer bundled in Nuxt 5
Nuxt 5 no longer depends on jiti. Files loaded outside the bundler (nuxt.config.ts, files in modules/, and layer configs) are now imported by the runtime itself. Nuxt 5 requires Node 22.19 or later where type stripping is on by default. Relative imports in these files need explicit extensions (e.g., './build/my-plugin.ts' instead of './build/my-plugin'). Type annotations are erased, but syntax that emits runtime code cannot be used: replace enums with const objects, namespaces with plain exports, and constructor parameter properties with explicit assignments.
Ship compiled JavaScript for published layers or modules
If you publish a layer or module for Nuxt 5, build to JavaScript before publishing. The runtime refuses to strip types from any file inside node_modules. A published entrypoint written in TypeScript cannot be loaded natively. If your package ships a nuxt.config, emit it as nuxt.config.mjs. This does not apply to layers inside your own project (layers/*/nuxt.config.ts loads natively).
experimental.externalVue removed in Nuxt 5
The experimental.externalVue option has been removed in Nuxt 5. Vue compiler dependencies are now always replaced with mock proxies in the server bundle when vue.runtimeCompiler is not enabled. This reduces server bundle size by approximately 860KB. If you previously set experimental.externalVue, remove it.
Vue Options API disabled by default in Nuxt 5
With compatibilityVersion: 5, Nuxt sets Vue's __VUE_OPTIONS_API__ feature flag to false, compiling the Options API runtime out of the client bundle. This reduces client bundle size by around 6 kB minified / 2 kB gzipped.
Re-enable Vue Options API in Nuxt 5
If any of your components use the Options API (export default { data() {}, methods: {}, ... }), re-enable it by setting `vue.optionsApi: true` in nuxt.config.ts. defineNuxtComponent remains unaffected.