Ryz Labs/Migrations/Vue 2 to Vue 3
Migrations

Vue 2 to Vue 3 and Nuxt 2 to Nuxt 4: A Migration Runbook

How to get a Vue 2 or Nuxt 2 codebase onto Vue 3 and current Nuxt without a rewrite: audit plugins, run the migration build, burn down warnings, then cut over.

A Vue 2 to Vue 3 migration is mostly an in-place upgrade, not a rewrite: you swap the runtime for the @vue/compat migration build, fix what it warns about component by component, then remove it. Nuxt 2 apps need a second track, because the Nuxt server and data-fetching APIs changed, so those usually move route group by route group behind a proxy. What decides success is your dependency audit: a single UI library or plugin with no Vue 3 release can block the whole upgrade, so find those blockers before you write any code.

Why teams migrate now

Both halves of the old stack are past end of life. The Vue team announced that "Vue 2 will reach End of Life (EOL) on December 31st, 2023." The final Vue 2 release on npm is 2.7.16, while the current Vue 3 release is 3.5.46, with 3.6 in release-candidate builds. On the meta-framework side, Nuxt 2 reached end of life on June 30, 2024. The last Nuxt 2 release is 2.18.1, and Nuxt's current release is 4.6.4.

There is also a clock on the main migration tool. The official migration build is described as "a build of Vue 3" with configurable Vue 2 behavior, and the Vue team plans to stop publishing it in a future minor release. If your plan depends on running under @vue/compat for a long time, that plan has an expiry you do not control.

For the business, that adds up to framework CVEs nobody upstream will fix, plugin authors who have moved their attention to Vue 3, and scanner findings that reappear every quarter. Engineers new to Vue learn the Composition API first, so the hiring pool keeps shifting away from you, and every sprint on Vue 2 adds code written against removed APIs.

Before you start: inventory and baseline

The Vue 3 upgrade is gated by your dependencies more than by your own code. Inventory them first.

The strangler-fig plan, phase by phase

Phase 0: Compatibility audit and blocker decisions

Turn the inventory into decisions. For each needs-replacement library, pick its replacement now and prototype the three hardest screens with it. For abandoned plugins, decide between forking, rewriting the small part you use, or dropping the feature. This is where Vue 3 projects stall, so do not move on with open blockers.

Done when: every Vue-touching dependency has a decision, UI library replacement prototyped, characterization suite green on Vue 2.

Phase 1: Clean up while still on Vue 2

Upgrade to Vue 2.7.16, the last Vue 2 release, and do every change that works on both versions. Replace filters with methods or computed properties (a formatCurrency function instead of a currency pipe). Replace the event bus with a tiny emitter such as mitt, or with store actions. Rename custom v-model usages so they are easy to find later. Move Vue.prototype globals behind a small module you can import. Migrate build tooling to Vite if you are on Vue CLI, since the Vite plugin for Vue 2 lets you change one variable at a time.

Done when: no filters, no event bus, no new code using removed APIs, lint rules (eslint-plugin-vue) set to flag them, suite green.

Phase 2: Switch the runtime to the migration build

Alias vue to @vue/compat in your bundler config, install the Vue 3 compiler, and set compilerOptions.compatConfig to MODE: 2 so the app runs with Vue 2 behavior by default. Upgrade Vue Router and Vuex to their Vue 3-compatible lines at the same time, because they cannot stay on Vue 2 versions under the new runtime. Replace new Vue() with createApp and move Vue.use calls to app.use.

Expect compile errors before runtime warnings: template syntax the Vue 3 compiler rejects, router setup (createRouter, createWebHistory, catch-all routes rewritten as /:pathMatch(.*)*), and Vue Test Utils changes (propsData becomes props, mocks and stubs move under global).

Done when: the app boots and the characterization suite passes under @vue/compat, with deprecation warnings logged but not yet fixed.

Phase 3: Burn down compat warnings, component by component

The migration build logs each Vue 2 behavior it emulates with a named flag, such as GLOBAL_MOUNT, INSTANCE_EVENT_EMITTER, INSTANCE_LISTENERS, COMPONENT_V_MODEL, OPTIONS_BEFORE_DESTROY and ATTR_FALSE_VALUE. Collect these from dev and staging into a single report keyed by flag and component, and work it down. Fix a component, then set compatConfig: { MODE: 3 } on that component so it runs as pure Vue 3 while its neighbors still run in compat mode.

Watch the behavioral changes that do not throw: attribute fallthrough now includes class, style and listeners via $attrs; boolean attributes set to false are removed rather than rendered as "false"; watchers on arrays no longer fire on mutation without deep: true; transition class names changed. These pass type checks and still change what users see.

This is also the moment to decide on the Options API versus the Composition API. You do not have to convert. Options API components run fine in Vue 3. Convert to script setup and composables where a component has grown mixins, since mixins are the hardest pattern to reason about and composables replace them cleanly.

Done when: zero compat warnings in staging traffic, every component at MODE: 3, suite green.

Phase 4: Replace the ecosystem layer

Move Vuex to Pinia store by store. Pinia stores are flat, typed and have no mutations, so each Vuex module becomes a defineStore with state, getters and actions. During the transition a Pinia store can read from the remaining Vuex store, so components migrate one at a time. Replace the UI library screen by screen with the choice from Phase 0, using a wrapper component per primitive (Button, DataTable, Dialog) so the swap happens in one file per primitive rather than in every template.

Done when: Vuex removed or reduced to modules with a scheduled removal, UI library swap complete for production screens, bundle size at or below baseline.

Phase 5: Remove @vue/compat and ship pure Vue 3

Drop the alias, install vue directly, set the global compat mode off, and run the full suite. Remove leftover compatibility shims and the old UI library package. Then upgrade within Vue 3 minors normally.

Done when: @vue/compat absent from the lockfile, dependency scan clean of Vue 2 packages, production metrics at or better than baseline.

If you are on Nuxt 2: the parallel track

Nuxt 2 to current Nuxt is more than a Vue upgrade, because the server layer, module system and data-fetching APIs changed. asyncData and fetch become useAsyncData and useFetch; @nuxtjs/axios becomes $fetch; the context argument becomes useNuxtApp; head() becomes useHead; plugins and middleware are rewritten with defineNuxtPlugin and defineNuxtRouteMiddleware; serverMiddleware moves to the server/ directory on Nitro; the store/ directory gives way to Pinia through @pinia/nuxt. Every Nuxt 2 module needs the same ready/replace/abandon audit as Vue plugins.

Nuxt Bridge exists for an in-place step, but for larger apps we prefer a route-group strangler: run the new Nuxt app and the Nuxt 2 app side by side behind a reverse proxy, move route groups one at a time (marketing pages first, then authenticated areas), and compare server-rendered HTML for each moved route against the snapshots from your baseline.

PhaseGoalKey techniqueDone when
0. AuditKnow every blockerPlugin and UI library compatibility audit, replacement prototypesA decision per Vue-touching dependency
1. Clean up on Vue 2Remove APIs that Vue 3 dropped2.7.16, filters to methods, event bus to mitt, Vite, eslint-plugin-vue rulesNo filters or bus, lint enforced
2. Migration buildBoot on the Vue 3 runtime@vue/compat alias, MODE: 2, createApp, router and store upgradesSuite passes under compat
3. Warning burn-downEvery component on pure Vue 3 behaviorPer-flag warning report, per-component MODE: 3, composables for mixinsZero warnings in staging
4. EcosystemModern store and UI layerVuex to Pinia store by store, wrapper components for the UI swapVuex and old UI library gone from production screens
5. Remove compatPure Vue 3 in productionDrop alias, global compat off, delete shimsNo @vue/compat, metrics at baseline
Nuxt trackNuxt 2 to current NuxtRoute groups behind a proxy, useAsyncData, Nitro server, SSR HTML diffAll route groups on new Nuxt, Nuxt 2 server off

Cutover and rollback

For a Vue SPA, the upgrade ships as a new build of the same app, so cutover is a release strategy rather than a routing problem. Build the Vue 3 bundle as a separate artifact, serve it to a canary slice with weighted target groups on your load balancer or a cookie-based split at the CDN, and keep the Vue 2 build deployed alongside. Because index.html points at hashed assets, switching back is a matter of serving the previous index.html.

For Nuxt, traffic moves by path. The proxy routes each route group to either the Nuxt 2 server or the new Nuxt server, with a flag to send internal users first. Before widening, diff server-rendered HTML for a sample of URLs on both servers: title, meta description, canonical, hreflang, JSON-LD and the main content block. Hydration mismatch warnings in the browser console are a release blocker, not noise.

Release gate before each widening step:

How to back out at each phase:

Risk matrix

RiskLikelihoodImpactMitigationEarly warning signal
UI library has no Vue 3 version or a renamed component APIHighHighDecide replacement in Phase 0; wrap primitives so the swap is one file eachPrototype screens take far longer than estimated
Abandoned Vue 2 plugin blocks the runtime switchMediumHighAudit every Vue.use package; fork, replace or remove before Phase 2Plugin throws on install under @vue/compat
Silent behavior changes (attribute fallthrough, false attributes, array watchers)HighMediumTrack named compat flags; characterization tests on visible output, not just unit testsStyling or toggles behave differently with no console error
Running under @vue/compat for too longMediumMediumWeekly warning count target; the Vue team plans to stop publishing the migration buildWarning count flat between releases
Event bus removal breaks cross-component flowsMediumMediumMap every $on listener to its emitter in Phase 1; replace with mitt or store actionsModals or toasts stop opening after a navigation
Vuex to Pinia loses persisted or SSR-hydrated stateMediumHighMigrate store by store; test persisted keys and SSR payload per storeUsers logged out or carts emptied after release
Nuxt 2 modules with no current Nuxt equivalentMediumHighModule audit in Phase 0; rebuild small modules as server routes or composablesBuild fails or features missing on moved route groups
SSR output drift hurts SEO on Nuxt pagesMediumHighHTML snapshot diffs of title, meta, canonical, JSON-LD before each route group movesSearch Console coverage or rich-result errors after a move
Mixins hide dependencies during Composition API conversionMediumLowConvert mixins to composables with explicit returns; leave stable Options API components aloneUndefined property errors after a refactor

Typical team shape

A Vue 3 upgrade rewards ecosystem depth more than headcount. The people we would put on it:

Many teams begin with a pod of 3 to 5 senior engineers (a tech lead plus engineers), and a full pod is about seven. Ryz engineers on your team start from $7,000 per month (our published range is $7,000–$15,000 per engineer per month, mostly mid-level to senior), quoted per team. Project cost = team size × months × monthly rate, and the months are driven by your blocker list and component count. Once you say go, engineers can typically start in under two weeks. Scope your team and we will send a plan, a price and the names of the engineers.

Where an AI pod helps (and where it doesn't)

Much of a Vue 3 upgrade is mechanical and well specified. Our AI pod puts coding assistants on that part:

The judgment calls stay with people: which UI library replaces the old one, which components deserve a Composition API rewrite, and whether a silent behavior change matters to a user. Generated diffs are reviewed by an engineer and gated by the journey suite and SSR snapshots, exactly like hand-written ones.

When not to migrate (yet)

If you need follow-the-sun coverage across Europe and Asia time zones, a Ryz team on US business hours is not the right fit.

Related

FAQ

Can we upgrade from Vue 2 to Vue 3 without rewriting the app?

Usually yes. The @vue/compat migration build runs Vue 2 style code on the Vue 3 runtime and warns about each emulated behavior, so you fix components one at a time and keep shipping. The parts that often need real rework are UI libraries and plugins with no Vue 3 release, and Nuxt 2 data fetching and server code.

Do we have to convert everything to the Composition API?

No. The Options API is fully supported in Vue 3. Convert where it pays off, mainly components built on mixins, shared logic that wants to be a composable, and stores moving to Pinia. Leave stable Options API components alone.

Should we move from Vuex to Pinia at the same time?

Not in the same step. Upgrade the runtime first with your Vuex store on its Vue 3-compatible version, then move to Pinia store by store. Splitting the two keeps each release small and each rollback simple.

How long does a Vue 2 to Vue 3 migration take?

There is no honest single number. The drivers are the count of components, how many plugins and UI library components lack Vue 3 versions, how much code uses filters, event buses and mixins, and whether you are also moving Nuxt 2. The blocker list from the dependency audit is the best predictor, so do that audit before anyone commits to a date.

What does a Vue 3 upgrade cost?

Multiply engineers by months by each engineer's monthly rate. We price per team once we have seen your dependency audit, your component count and whether Nuxt is in scope, so the number tracks your real blockers.

Questions we didn't answer? Email info@ryzlabs.com.

Thanks — your message has been sent. We’ll get back to you soon.

Something went wrong while sending your message. Please try again or email info@ryzlabs.com.

Explore Ryz Labs

Software development servicesAI development companyIndustriesStaff augmentationAI pod teamsNearshore software developmentHire engineers by roleEngineer ratesGuidesBuyer guidesCase studiesHow we vet engineers

Ryz Labs

Senior engineers on your team. AI pod teams that ship.

Tell us what you're building. You get a scoped plan, a price and the names of the people who would do the work.

  • Only the top 1% of tens of thousands interviewed make it
  • On US business hours, including New York hours
  • Trusted by Fortune 500 engineering teams

Tell us who you need

A Ryz partner replies with a scoped team plan.

Start a conversation →

Prefer to talk? Book a 15-min call →