Vue.js/Vue 3 migration

MediaWiki currently bundles the migration build of Vue 3, which provides backwards compatible behavior so that code written for Vue 2 continues to work. We would like to switch from the migration build to the regular build of Vue 3 (without the compatibility features). In order for that to happen, code that was originally written for Vue 2 and still relies on these compatibility features has to be migrated first.

Migration steps

See also Vue's migration guide, specifically the breaking changes section and the upgrade workflow section.

• Run your code in debug mode (by adding ?debug=true to the URL)
• Look for migration warnings. These begin with something like [Vue warn]: (deprecation FOO_BAR)(some of these can be ignored, see below)
• Address the migration warnings one by one. Some warnings include a link to a page explaining the warning and how to resolve it; for the others, look up the all-caps deprecation name (FOO_BAR in the example above) in this table.
• Repeat this process until no more migration warnings appear (except for the ones that can be safely ignored). Since some warnings only trigger at runtime, try to exercise all the paths in your code to make sure you catch all the warnings.
• Update transition classes where needed. There are no warnings for these, so you'll have to audit your <transition> tags and associated -leave and -enter CSS classes manually.
• Add compatConfig: { MODE: 3 }, compilerOptions: { whitespace: 'condense' }, to the component definition object of each of your components. This disables the compatibility behavior for your component. Test that your code still works.
• Lookup for any calls to the .use() method of the global Vue instance eg: Vue.use( Vuex ) and refactor them. See breaking-changes/global-api. Specifically for Vuex 4, passing a store to the application should be enoughapp.use( store ). See migrating-to-4-0-from-3-x.html#installation-process.
• Test your changes with the non-compat version of Vue 3 by downloading this core change.

Migration warnings that can be ignored

Some of the migration warnings you will see come from MediaWiki core's Vue 2 compatibility code, so you can't fix them. Others appear even in migrated code. The following warnings can be safely ignored:

• [Vue warn:] Directive "i18n-html" has already been registered in target app.
  • This warning comes from compatibility code in MW core that ensures that the v-i18n-html directive works in code targeting Vue 2.
• [Vue warn]: (deprecation GLOBAL_PROTOTYPE) Vue.prototype is no longer available in Vue 3. Use app.config.globalProperties instead.
  • This warning comes from compatibility code in the i18n plugin. However, if your code adds its own plugins, this warning may mask warnings in your plugin code. Check your plugin code to make sure it doesn't use Vue.prototype, but uses app.config.globalProperties instead.
• ATTR_FALSE_VALUE warnings followed by ^ The above deprecation's compat behavior is disabled and will likely lead to runtime errors
  • Unmigrated code may throw ATTR_FALSE_VALUE warnings. Once these are addressed and compatConfig: { MODE: 3 } is set, these warnings, frustratingly, don't go away, but are instead followed by another warning about the compat behavior being disabled. You can ignore these as long as you correctly handle the new Vue 3 behavior for setting attributes to false.