Page MenuHomePhabricator

Write guidelines for working with the Vue 3 migration build that teams can reference
Closed, ResolvedPublic

Description

We have some new Codex/Vue 3 features hitting production soon (Typeahead Search, soon the Nearby Pages port, Growth Team features, etc). MediaWiki is currently shipping the Migration Build of Vue 3 in production, which will preserve Vue 2 behavior by default, allowing developers to opt-in to Vue 3 behavior on a feature-by-feature, component-by-component basis.

We should develop some guidelines (on-wiki) that teams can reference to help them work with the compatibility build and prepare for a world that is fully migrated to Vue3. Here are some questions such a guide should address:

  • Should new code generally set compatConfig: { MODE: 3 } at the top of every component (or at the app level)?
  • What warnings can be safely ignored? GLOBAL_PROTOTYPE, whitespace, attribute false behavior?
  • Any specific things that people should watch out for?

Event Timeline

I dug into this a bit deeper today, and here are some recommendations based on what I've found so far:

  • New code should set compatConfig: { MODE: 3 } and compilerOptions: { whitespace: 'condense' } at the top of every component definition.
    • Setting compatConfig at the app level is unfortunately not possible. Setting compilerOptions at the app level is possible with app.config.compilerOptions.whitespace = 'condense'; (where app is the object returned by createMwApp). We could recommend that, although it would only be safe for apps that are entirely Vue 3, with none of the external components coming from libraries etc requiring Vue 2 compatibility. That means it should be safe for most apps, since most apps just use their own components and Codex components.
  • The following warnings can be safely ignored:
    • The GLOBAL_PROTOTYPE warning whose stack trace includes Vue.createMwApp. This warning is caused by code in MW core that is necessary to provide Vue 2 compatibility.
    • The warning Directive 'i18n-html' has already been registered in target app.. This warning is also caused by code in MW core that provides Vue 2 compatibility.
    • ATTR_FALSE_VALUE warnings coming from Codex components (component name starts with Cdx) or in other components that are known to be newly written in or fully converted to Vue 3. Often these warning are followed by a message styled as an error that says ^ The above deprecation's compat behavior is disabled and will likely lead to runtime errors, which can also be ignored.
  • Some things people should watch out for when migrating old code written for Vue 2:
    • Transition CSS classes need to be updated, and there are no migration warnings for this
    • The behavior of Vue.createMwApp( App ).mount( '#container' ) differs from new Vue( { el: '#container', ... } ). The latter (Vue 2 style) replaces #container with the rendered app, while the former (Vue 3 style) replaces the contents of #container with the rendered app (i.e. all pre-existing children of #container are deleted, and the app is put inside of #container). Most code (even code that otherwise has not been migrated to Vue 3) already uses the Vue 3 style. But some code doesn't, and when migrating that code you should be careful about the DOM structure change this causes, which can break CSS rules expecting the old structure.
    • Setting whitespace: 'condense' (which is the default in Vue 3) when the code was originally written to expect the old Vue 2 whitespace behavior can cause layout bugs in some cases. Sometimes you may need to manually insert a space between two tags, using this trick.
    • If you're using compiled templates (as the output of a build step) that have been compiled with Vue 3, you have to add compatConfig: { MODE: 3 } to each component definition, either in the source code, or dynamically when importing it into MediaWiki using code like this (we should factor out that recursivelyMarkAsVue3 function so it can be reused in other places; right now there are already two copies of it).