Vue 2 vs Vue 3 and Composition API vs Options API: complete comparison

Vue 3 launched in late 2020. Five years later, Vue 2 has been officially end-of-life since December 2023, yet migration is still dragging in many projects. Between the reactivity rewrite, the Composition API that throws people off at first, and Vite replacing webpack — there's plenty of reason to stall. Here's what actually changed, what it means for your code, and how to choose between the two APIs.

Vue 2 vs Vue 3: what changed in practice

The reactivity system

This is the deepest change. Vue 2 uses Object.defineProperty to observe mutations — with its well-known limitations: no detection of dynamically added properties, no detection on array indexes. Hence the Vue.set() and this.$set() calls that clutter Vue 2 code.

Vue 3 uses ES2015 Proxy. The entire object is intercepted, not property by property. No more $set, direct mutations are detected natively:

// Vue 2 — adding a reactive property after creation
this.$set(this.user, 'email', 'odilon@example.com') // required

// Vue 3 — works directly
this.user.email = 'odilon@example.com' // reactive automatically

Performance and bundle size

Vue 3 is tree-shakable. Unused features (Transition, KeepAlive, Teleport...) are not included in the final bundle if they aren't imported. Vue 2 included the full runtime regardless.

In practice on an average project: runtime bundle reduced by roughly 40% with Vue 3 vs Vue 2. The reactive diff is also faster thanks to a rewritten virtual DOM patching strategy (static template analysis at compile time).

TypeScript

Vue 2 had a patched-together TypeScript support via vue-class-component and decorators. Functional, but tedious. Vue 3 was rewritten in TypeScript from scratch — types are native, inference works without any special configuration in components.

Fragments, Teleport, Suspense

Three structural additions that were missing in Vue 2:

Fragments: a component can return multiple root elements — no more pointless wrapper <div>
Teleport: render HTML into another DOM node (modals, tooltips) without working around CSS with fragile position: fixed hacks
Suspense: handle async component loading states natively

What breaks during migration

The Vue 3 breaking changes that cause the most damage during migration:

$listeners removed — merged into $attrs
$children removed — use ref or provide/inject
filters removed — use methods or computed properties
v-model: the event is now update:modelValue instead of input
Vuex → Pinia (Vuex 5 never shipped)
Vue Router 4 with some API changes

On a large Vue 2 project with lots of filters, $listeners, and Vuex everywhere, migration takes time. The automated migration via @vue/compat helps but doesn't solve everything.

Options API vs Composition API

This is the question that comes up most often when moving to Vue 3. The short answer: both are officially supported, permanently. It's not a replacement but an alternative.

Options API — quick reminder

export default {
  name: 'UserProfile',
  props: {
    userId: String,
  },
  data() {
    return {
      user: null,
      loading: false,
    }
  },
  computed: {
    displayName() {
      return this.user?.name ?? 'Unknown'
    },
  },
  methods: {
    async fetchUser() {
      this.loading = true
      this.user = await api.getUser(this.userId)
      this.loading = false
    },
  },
  mounted() {
    this.fetchUser()
  },
  watch: {
    userId(newId) {
      this.fetchUser()
    },
  },
}

Composition API — same component

import { ref, computed, watch, onMounted } from 'vue'
import { useUserApi } from '@/composables/useUserApi'

export default {
  name: 'UserProfile',
  props: {
    userId: String,
  },
  setup(props) {
    const user = ref(null)
    const loading = ref(false)

    const displayName = computed(() => user.value?.name ?? 'Unknown')

    async function fetchUser() {
      loading.value = true
      user.value = await api.getUser(props.userId)
      loading.value = false
    }

    watch(() => props.userId, fetchUser)
    onMounted(fetchUser)

    return { user, loading, displayName }
  },
}

Or with <script setup> (the recommended syntax in Vue 3):

// <script setup>
import { ref, computed, watch, onMounted } from 'vue'

const props = defineProps({ userId: String })
const user = ref(null)
const loading = ref(false)

const displayName = computed(() => user.value?.name ?? 'Unknown')

async function fetchUser() {
  loading.value = true
  user.value = await api.getUser(props.userId)
  loading.value = false
}

watch(() => props.userId, fetchUser)
onMounted(fetchUser)

Everything declared inside <script setup> is automatically exposed to the template — no more return {}.

Strengths and weaknesses

Options API

Strengths

Rigid and predictable structure — everyone knows where to find data, methods, computed properties
Low learning curve — ideal for onboarding junior devs or devs coming from other frameworks
Very readable on small components — everything is organized by option type
Abundant documentation, examples everywhere on Stack Overflow and legacy projects

Weaknesses

Business logic gets fragmented across data, methods, computed, watch — impossible to keep one "feature" coherent in a single block
Reusing logic between components forces you through mixins — which create naming collisions and make dependencies opaque
Tedious TypeScript: this inside methods doesn't infer well, annotations everywhere
On large components (200+ lines), navigation becomes painful: data is at the top, the method that modifies it is at the bottom, the watcher is somewhere else

Composition API

Strengths

Business logic can be co-located: everything related to fetchUser (state, method, watcher) stays together
Composables cleanly replace mixins: reusable logic is an explicitly imported function, no magic, no collisions
Native TypeScript: ref<User | null>(null), no this, full inference
More effective tree-shaking: only the Vue functions you use are imported

Weaknesses

More verbose on small components — importing ref, computed, onMounted explicitly for 20 lines of logic
The .value on refs is constant friction, a source of bugs (forgetting .value in JS but not in the template)
Without discipline, <script setup> can turn into a grab-bag — structural freedom has a cost if the team doesn't enforce conventions
Less intuitive for someone coming from Vue 2 or React Class Components — the learning curve is real

Direct comparison on concrete cases

Logic reuse: mixins vs composables

This is where the Composition API wins most clearly. A Vue 2 mixin to handle pagination:

// Vue 2 — mixin
export const paginationMixin = {
  data() {
    return {
      page: 1,
      perPage: 10,
      total: 0,
    }
  },
  computed: {
    totalPages() {
      return Math.ceil(this.total / this.perPage)
    },
  },
  methods: {
    nextPage() { this.page++ },
    prevPage() { this.page-- },
  },
}

// Usage — where data.page comes from is not obvious
export default {
  mixins: [paginationMixin],
  // where does this.page come from? mystery for a new dev
}

// Vue 3 — composable
export function usePagination(initialPerPage = 10) {
  const page = ref(1)
  const perPage = ref(initialPerPage)
  const total = ref(0)

  const totalPages = computed(() => Math.ceil(total.value / perPage.value))

  function nextPage() { page.value++ }
  function prevPage() { page.value-- }

  return { page, perPage, total, totalPages, nextPage, prevPage }
}

// Usage — explicit
const { page, total, nextPage } = usePagination(20)
// we know exactly where page comes from

TypeScript: the concrete difference

// Options API with TypeScript — tedious
export default defineComponent({
  data(): { user: User | null; loading: boolean } { // manual annotation
    return { user: null, loading: false }
  },
  methods: {
    async fetchUser(id: string): Promise<void> {
      this.user = await getUser(id) // this isn't always inferred
    },
  },
})

// Composition API — native inference
const user = ref<User | null>(null)
const loading = ref(false) // inferred as ref<boolean>

async function fetchUser(id: string) {
  user.value = await getUser(id) // correctly typed without annotation
}

Conclusion: when to choose which

Options API if:

You're migrating a Vue 2 project and want to minimize change
The team is junior or comes from other MVC frameworks
Components are small and logic isn't reused
You want a framework-enforced structure without the discipline overhead

Composition API if:

You're starting a new Vue 3 project — it's the ecosystem's default choice
You're using TypeScript seriously
You have complex logic to reuse across components
Components are growing — logic co-location becomes a real advantage

What I wish I'd known when starting with Vue 3: both APIs coexist in the same project. A simple form component can stay in Options API while a complex component with 5 composables switches to Composition API. No need to choose once and for all.

On my recent projects, I use the Composition API by default with <script setup> — TypeScript demands it — and composables for everything touching API calls, complex local state management, and DOM interactions (resize observer, intersection observer, etc.). Options API stays for simple presentational components where the rigid structure is an advantage rather than a constraint.

推荐订阅源

DEV Community