Vue3 Gotchas: When to Use Composition vs Options API and Other Pitfalls

Introduction

In this article the author shares a personal Vue3 learning checklist and summarizes frequently confused points and practical pitfalls encountered while adopting Vue3 in a real project.

Common Vue3 Questions

1. Must I use the Composition API for every Vue3 component?

The answer is no. Vue3 still fully supports the Options API. Use the Options API for simple components like toast or button, and the Composition API for more complex business logic where you want to extract reusable logic into hooks.

2. Does mixing Options API and Composition API affect performance?

No performance impact; the choice should be driven by code organization rather than speed concerns.

3. Why is this unavailable inside setup() ?

During setup() the component instance has not been created yet, so this does not refer to the component. Only props are accessible; other instance properties such as local state or computed values must be accessed via returned refs.

4. reactive vs ref

reactive

turns an object into a reactive proxy, while ref creates a reactive wrapper whose value is accessed via ref.value. toRefs can convert a reactive object’s properties into individual refs, simplifying destructuring.

5. Is Vue3’s reactivity faster than Vue2’s?

Vue3 replaces Object.defineProperty with Proxy, enabling lazy observation: nested objects become reactive only when accessed, which improves initialization performance compared to Vue2’s eager recursion.

6. Vue Composition API vs React Hooks

The two APIs look similar; a detailed comparison is linked in the original article.

Practical Migration Pitfalls

1. Experimental <script setup> warnings

[@vue/compiler-sfc] <script setup> is still an experimental proposal.
Follow its status at https://github.com/vuejs/rfcs/pull/227.

[@vue/compiler-sfc] When using experimental features,
it is recommended to pin your vue dependencies to exact versions to avoid breakage.

[@vue/compiler-sfc] `defineProps` is a compiler macro and no longer needs to be imported.

2. Missing lifecycle methods in setup()

setup(props, { emit }) {
  const rootRef = ref(null)
  const scroll = useScrolll(rootRef, props, emit)

  return {
    rootRef,
    scroll
  }
}

// scroll.js
scrollVal.on('scroll', pos => {
  emit('scroll', pos)
})

3. Computed API changes

// Vue2.x
computed: {
  loading() {
    return !this.list.length
  }
},

// Vue3.x
const loading = computed(() => !this.list.length)
const titleList = computed(() => props.data.map(item => item.title))

4. Watch deep option

// Vue2.x
watch: {
  'data.distance'(newVal) {
    if (newVal === constants.DISTANCE_ON) {
      // ...
    }
  }
},

// Vue3.x
watch(
  () => this.data.distance,
  (newVal) => {
    if (newVal === constants.DISTANCE_ON) {
      // ...
    }
  },
  { deep: true }
)

5. Filters removed

// Vue2.x
filters: { dateFormat },

// Vue3.x
const dateFormat = computed(() => {
  // just a method
})

6. .sync replaced by v-model

// Vue2.x
<basic-info-dialog :shown.sync="dialogFormVisible">
<ChildComponent v-bind:name.sync="name" />

// Vue3.x
<basic-info-dialog v-model:shown="dialogFormVisible"></basic-info-dialog>

Conclusion

Migration continues to reveal new challenges; keep experimenting and learning from each pitfall.