You have a Vue 2 project running for three years. It works, but every time you add a new feature, you wonder if rewriting it is worth it. Or you're about to start a new frontend and want to know if Vue 3 is the right call or if you should stick with the version you know.
We, at Meteora Web, have been working with Vue since version 2. We've seen both the beauty and the limitations. With Vue 3, the framework was rewritten from scratch, and the differences go far beyond aesthetics. The way we write components, manage state, and optimize performance has changed. In this guide, we’ll cover the real differences with concrete examples and help you decide whether and how to migrate.
The Engine: Proxy vs Object.defineProperty
The deepest difference between Vue 2 and Vue 3 lies in the reactivity system. Vue 2 used Object.defineProperty to intercept reads and writes on object properties. It works, but has major limitations:
- It doesn't detect new property additions (you need
Vue.set). - It doesn't work well with arrays modified by index or length (you must use
spliceorVue.set). - Performance degrades on large objects because each property is converted individually.
Vue 3 leverages the native JavaScript Proxy API. A Proxy wraps the entire object and intercepts any operation: read, write, delete, enumeration. No limits. No more Vue.set. Add a property whenever you want, modify arrays by index directly.
Practical example: reactivity comparison
// Vue 2 – watch out for property addition
data() {
return { user: { name: 'Mario' } }
},
methods: {
addAge() {
// Not reactive
this.user.age = 30;
// Must use Vue.set
Vue.set(this.user, 'age', 30);
}
}
// Vue 3 – Proxy makes it work always
import { reactive } from 'vue';
export default {
setup() {
const user = reactive({ name: 'Mario' });
function addAge() {
user.age = 30; // reactive without hacks
}
return { user, addAge };
}
}
This means fewer bugs, less boilerplate, and a more natural state management. You'll feel the difference when dealing with nested objects or large arrays. We've fixed several legacy projects by switching to Vue 3: numbers show the reactivity system is about 2-4 times faster in frequent-update scenarios.
Options API vs Composition API: Not mandatory, but game-changing
Vue 3 introduces the Composition API as an alternative to the classic Options API. It's not mandatory: you can still write components with data, methods, computed in Vue 3. The real difference appears when handling complex logic.
With Options API, logic is scattered across options: if a component has three different features, their data, methods, and watch are mixed in separate sections. Reusing pieces of logic between components becomes painful. The Composition API lets you group logic per feature using the setup function and composables.
Counter component: Options vs Composition
<!-- CounterOptions.vue – Vue 2 style, works in Vue 3 too -->
<template>
<div>
<p>{{ count }}</p>
<button @click="increment">+1</button>
</div>
</template>
<script>
export default {
data() { return { count: 0 } },
methods: { increment() { this.count++ } }
}
</script>
<!-- CounterComposition.vue – Vue 3 Composition API -->
<template>
<div>
<p>{{ count }}</p>
<button @click="increment">+1</button>
</div>
</template>
<script setup>
import { ref } from 'vue';
const count = ref(0);
const increment = () => count.value++;
</script>
The <script setup> syntax is the most used in Vue 3. Less boilerplate, ref instead of data, functions directly inside. The real benefit comes when you extract logic into a composable:
// useCounter.js
export function useCounter(initialValue = 0) {
const count = ref(initialValue);
const increment = () => count.value++;
const decrement = () => count.value--;
return { count, increment, decrement };
}
// in a component
<script setup>
import { useCounter } from './useCounter';
const { count, increment } = useCounter(10);
</script>
This pattern is similar to React hooks (check our guide on React Fundamentals for a comparison). The difference: in Vue, reactivity is automatic, no dependency arrays needed.
When should you use Composition API? As soon as your component has more than one independent logic, or when you need to reuse functionality across components. Examples: form handling, API data fetching, timers. For simple components like a button, Options API is perfectly fine.
Ecosystem: Vite, Pinia, Vue Router 4
Vue 3 also brought changes to the ecosystem. Vite is the new bundler (replaces Vue CLI). We use it in every Vue 3 project: instant hot reload, blazing fast builds, minimal configuration. If you’re migrating, expect to switch from Webpack to Vite.
Pinia has replaced Vuex as the official state management library. Lighter, full TypeScript, no need for mutations (you mutate state directly). Vue Router 4 is similar to Router 3 but fully integrated with Composition API and typed.
A practical note: many third-party libraries (UI frameworks, validation) have been rewritten for Vue 3. If you use something like Vuetify or Element UI, check compatibility. Some plugins have separate versions (e.g., BootstrapVue for Vue 2, bootstrap-vue-next for Vue 3).
Performance and bundle size: concrete numbers
Vue 3 has a smaller and faster runtime. Official data:
- Bundle size gzipped: Vue 2 ~22 KB, Vue 3 ~13 KB (with tree-shaking).
- Rendering speed: up to 1.3-2x faster in virtual DOM diffing and patching.
- Memory: lower allocation thanks to the rewritten reactivity system.
We measured a Vue 2 e-commerce project: the frontend was around 120 KB after compression. Moving to Vue 3, without major changes beyond reactivity and store replacement, it dropped to 80 KB. For a mobile user, that's 1-2 seconds less loading time.
New features: Teleport, Fragments, Suspense, Multiple v-model
Vue 3 introduces features that required workarounds in Vue 2:
- Teleport: moves content to another DOM node (useful for modals, tooltips).
- Fragments: components can have multiple root nodes without a wrapper div.
- Suspense: handles asynchronous components (data fetching, lazy loading).
- Multiple v-model: you can use more than one
v-modelon a single component (e.g.,v-model:name,v-model:email).
None of these are mandatory, but they greatly simplify common use cases.
When to migrate (and when not to)
Not every Vue 2 project needs an immediate migration. Our rule of thumb:
- New project? Always Vue 3. The ecosystem is mature, performance is better, Composition API is the future.
- Large existing project (thousands of components): Evaluate the cost of migration. If your project is stable and you don't have performance or maintainability issues, you may postpone. Start with
@vue/compat(Vue 3 with Vue 2 compatibility) for a gradual transition. - Project with frequent new development: Migration is worth it if you want to leverage new features or need better native TypeScript support (Vue 3 has much better TypeScript integration).
- Project using libraries not compatible with Vue 3: Check if Vue 3 alternatives exist. If the libraries are critical and unmaintained, you might be stuck for years.
We at Meteora Web have handled both scenarios. In a order management project for a SME, we started with @vue/compat, rewriting about 40 components out of 200; the rest stayed in Vue 2 style until full migration. This let us use Vite and Proxy from day one without blocking development.
How to migrate: step by step
Here is the approach we recommend:
- Switch to Vue 3 in compat mode: Install
@vue/compat(npm install vue@3 @vue/compat) and configurecreateVueAppwithruntimeCompat: { MODE: 2 }. Everything works as before, but with the Vue 3 engine underneath. - Update dependencies: Vue Router 4, Pinia (or Vuex 4), third-party libraries.
- Replace Vue CLI with Vite: Create a Vite project, move your structure, configure aliases and plugins. Builds become instantly faster.
- Rewrite components one by one: Start with the most complex ones (those with intricate logic) to switch to Composition API. Leave simple components untouched if not necessary.
- Remove Vue.set and Vue.delete: They are no longer needed. Replace with direct assignments.
- Remove unnecessary wrapper divs thanks to fragments.
- Test and audit: Verify that the bundle size is smaller and performance improved.
# Example of compat mode installation
npm i vue@3 @vue/compat vue-router@4 pinia
# Vite
npm create vite@latest my-project -- --template vue
For a practical example of setting up a Vue 3 project with Laravel, check our guide on Laravel 12 (the two frameworks often go together).
In summary – what to do now
- If you're starting a new project: Use Vue 3 with
<script setup>, Vite, and Pinia. Don't look back. - If you have a stable Vue 2 project: Open your console and check the current bundle size. If it's over 100 KB gzipped, migration will give a measurable speed boost.
- Audit your dependencies: List every Vue 2 plugin you use and search for its Vue 3 counterpart. If you find blockers, plan the replacement.
- Try compat mode: Clone your project, install
@vue/compat, and see if everything works. If it does, you already have a gradual plan. - Don't migrate everything at once: Use a component-by-component approach. Start with the components that give you the most pain.
Vue 3 is not a fad: it's a technical leap. We use it every day, and the difference shows in the projects we deliver. If you have questions or want to discuss your specific case, reach out – we’re here to help businesses make the right choice, not the easiest one.
Sponsored Protocol
