Migration to Vue 3

Preparations for a Vue 3 migration are tracked in epic &3174

In order to prepare for the eventual migration to Vue 3.x, we should not use the following deprecated features in the codebase:

NOTE: Our linting rules block the use of these deprecated features.

Vue filters

Why?

Filters are removed from the Vue 3 API completely.

What to use instead

Component's computed properties / methods or external helpers.

Event hub

Why?

$on, $once, and $off methods are removed from the Vue instance, so in Vue 3 it can't be used to create an event hub.

When to use

If you are in a Vue app that doesn't use any event hub, try to avoid adding a new one unless absolutely necessary. For example, if you need a child component to react to its parent's event, it's preferred to pass a prop down. Then, use the watch property on that prop in the child component to create the desired side effect.

If you need cross-component communication (between different Vue apps), then perhaps introducing a hub is the right decision.

What to use instead

Vue documentation recommends using the mitt library. It's relatively small (200 bytes, compressed) and has a clear API:

import mitt from 'mitt'

const emitter = mitt()

// listen to an event
emitter.on('foo', e => console.log('foo', e) )

// listen to all events
emitter.on('*', (type, e) => console.log(type, e) )

// fire an event
emitter.emit('foo', { a: 'b' })

// working with handler references:
function onFoo() {}

emitter.on('foo', onFoo)   // listen
emitter.off('foo', onFoo)  // unlisten

Event hub factory

We have created a factory that you can use to instantiate a new mitt-based event hub. This makes it easier to migrate existing event hubs to the new recommended approach, or to create new ones.

import createEventHub from '~/helpers/event_hub_factory';

export default createEventHub();

Event hubs created with the factory expose the same methods as Vue 2 event hubs ($on, $once, $off and $emit), making them backward compatible with our previous approach.

<template functional>

Why?

In Vue 3, { functional: true } option is removed and <template functional> is no longer supported.

What to use instead

Functional components must be written as plain functions:

import { h } from 'vue'

const FunctionalComp = (props, slots) => {
  return h('div', `Hello! ${props.name}`)
}

It is not recommended to replace stateful components with functional components unless you absolutely need a performance improvement right now. In Vue 3, performance gains for functional components are negligible.

Old slots syntax with slot attribute

Why?

In Vue 2.6 slot attribute was already deprecated in favor of v-slot directive. The slot attribute usage is still allowed and sometimes we prefer using it because it simplifies unit tests (with old syntax, slots are rendered on shallowMount). However, in Vue 3 we can't use old syntax anymore.

What to use instead

The syntax with v-slot directive. To fix rendering slots in shallowMount, we need to stub a child component with slots explicitly.

<!-- MyAwesomeComponent.vue -->
<script>
import SomeChildComponent from './some_child_component.vue'

export default {
  components: {
    SomeChildComponent
  }
}

</script>

<template>
  <div>
    <h1>Hello GitLab!</h1>
    <some-child-component>
      <template #header>
        Header content
      </template>
    </some-child-component>
  </div>
</template>

// MyAwesomeComponent.spec.js

import SomeChildComponent from '~/some_child_component.vue'

shallowMount(MyAwesomeComponent, {
  stubs: {
    SomeChildComponent
  }
})

Props default function this access

Why?

In Vue 3, props default value factory functions no longer have access to this (the component instance).

What to use instead

Write a computed prop that resolves the desired value from other props. This will work in both Vue 2 and 3.

<script>
export default {
  props: {
    metric: {
      type: String,
      required: true,
    },
    title: {
      type: String,
      required: false,
      default: null,
    },
  },
  computed: {
    actualTitle() {
      return this.title ?? this.metric;
    },
  },
}

</script>

<template>
  <div>{{ actualTitle }}</div>
</template>

In Vue 3, the props default value factory is passed the raw props as an argument, and can also access injections.