Vue-BridgeCompatibility Listing
This Page details all of the differences between Vue 2 and 3 that you will have to be aware of and account for when writing cross-compatible code.
Each of the points listed has it's own dedicated page explaining how to deal with it, and how to do so in the safest and easiest way possible.
Legend
| Badge | Description |
|---|---|
| 🔍 Eslint | Compat can be ensured by an eslint rule |
| ✅ Plugin | Compat is (at least partially) provided by the @vue-bridge/runtime plugin |
| 👩🏽💻 Discipline | Compat needs to be ensured by the developer without tooling support. Following these rules is generally straightforward and low-risk |
| ⚠️ Pitfall | Like 👩🏽💻 Discipline, but with a noteworthy risk of introducing bugs because these are easy to miss |
This can seem like a lot, so make sure to read the Guide to learn how to navigate all of this.
🛑 Incompatible
These concern features / syntax that is straight up incompatible, though some have workarounds.
- Don' use Multiple Root elements / Fragments 🔍 Eslint
- Don't use
v-model:arg&v-bind.sync🔍 Eslint - Don't use
v-on.native(removed in Vue 3) 🔍 Eslint - Don't use template
refonv-forelement 👩🏽💻 Discipline - Don't use Filters (removed in Vue 3) 🔍 Eslint
🛠 Compatibility achievable
This section covers featues that are mostly the same in Vue 2/3, but have some special cases and situations where the developer has to make sure to account for limitations or differences.
Reactivity
- Always Respect Vue 2 Reactivity Caveats ⚠️ Pitfall ✅ Plugin
- Don't use Maps & Sets in Reactive Data 👩🏽💻 Discipline
Transitions
- Attention when using
<Transition>as root element 👩🏽💻 Discipline - Always supply both Transition class name versions 👩🏽💻 Discipline
- Always set
tagprop on Transition Group 👩🏽💻 Discipline
$attrs / $listeners / inheritAttrs
- Respect version-specific content of
$attrs&$listeners🔍 Eslint✅ Plugin - Always respect
$attrsandclass/stylespecial treatment in Vue 2 🔍 Eslint✅ Plugin
Misc
- Always configure the
emits:option 🔍 Eslint - Always respect
v-bindorder precedence of Vue 3 ⚠️ Pitfall - Always use
nullto remove non-boolean attrs. notfalse👩🏽💻 Discipline - Always respect Vue 3's
v-if-v-forprecedence 🔍 Eslint - Always use the
isprop with special<component>🔍 Eslint
🧬 Polyfilled by @vue-bridge/runtime
v-modelprop and event names (patched for Vue 2 by plugin) ✅ Pluginthis.$set/this.$delete(removed in Vue 3) ✅ Plugin- Some Component Lifecycle Hooks (patched for Vue 2 by this plugin) ✅ Plugin
- Custom Directives (Lifecycle hook names patched for Vue 2 by plugin)✅ Plugin
- TODO:
defineAsyncComponent()(only exists in Vue 3) 🔍 Eslint✅ Plugin