Webmasters Gallery

I recently had an opportunity to try the new Vue Composition API in a real project to check where it might be useful and how we could use it in the future.

Until now, when we were creating a new component we were using Options API. That API forced us to separate the component’s code by options, meaning that we needed to have all reactive data in one place (data), all computed properties in one place (computed), all methods in one place (methods), and so on.

As it is handy and readable for smaller components, it becomes painful when the component gets more complicated and deals with multiple functionalities. Usually, logic related to one specific functionality contains some reactive data, computed property, a method or a few of them; sometimes it also involves using component lifecycle hooks. That makes you constantly jump between different options in the code when working on a single logical concern.

The other issue that you may have encountered when working with Vue is how to extract a common logic that can be reused by multiple components. Vue already has few options to do that, but all of them have their own drawbacks (e.g. mixins, and scoped-slots).

The Composition API brings a new way of creating component, separating code and extracting reusable pieces of code.

Let’s start with code composition within a component.

Code composition

Imagine you have a main component that sets up few things for your whole Vue app (like layout in Nuxt). It deals with the following things:

• setting locale
• checking if the user is still authenticated and redirects them if not
• preventing the user from reloading the app too many times
• tracking user activity and reacting when the user is inactive for specific period of time
• listening on an event using EventBus (or window object event)

Those are just a few things the component can do. You can probably imagine a more complex component, but this will serve the purpose of this example. For the sake of readability, I am just using names of the props without the actual implementation.

This is how the component would look like using Options API:

<template>
  <div id="app">
    ...
  </div>
</template>

<script>
export default {
  name: 'App',

  data() {
    return {
      userActivityTimeout: null,
      lastUserActivityAt: null,
      reloadCount: 0
    }
  },

  computed: {
    isAuthenticated() {...}
    locale() {...}
  },

  watch: {
    locale(value) {...},
    isAuthenticated(value) {...}
  },

  async created() {
    const initialLocale = localStorage.getItem('locale')
    await this.loadLocaleAsync(initialLocale)
  },

  mounted() {
    EventBus.$on(MY_EVENT, this.handleMyEvent)

    this.setReloadCount()
    this.blockReload()

    this.activateActivityTracker()
    this.resetActivityTimeout()
  },

  beforeDestroy() {
    this.deactivateActivityTracker()
    clearTimeout(this.userActivityTimeout)
    EventBus.$off(MY_EVENT, this.handleMyEvent)
  },

  methods: {
    activateActivityTracker() {...},
    blockReload() {...},
    deactivateActivityTracker() {...},
    handleMyEvent() {...},
    async loadLocaleAsync(selectedLocale) {...}
    redirectUser() {...}
    resetActivityTimeout() {...},
    setI18nLocale(locale) {...},
    setReloadCount() {...},
    userActivityThrottler() {...},
  }
}
</script>

As you can see, each option contains parts from all functionalities. There is no clear separation between them and that makes the code hard to read, especially if you are not the person who wrote it and you are looking at it for the first time. It is very hard to find which method is used by which functionality.

Let’s look at it again but identify the logical concerns as comments. Those would be:

• Activity tracker
• Reload blocker
• Authentication check
• Locale
• Event Bus registration

<template>
  <div id="app">
    ...
  </div>
</template>

<script>
export default {
  name: 'App',

  data() {
    return {
      userActivityTimeout: null, // Activity tracker
      lastUserActivityAt: null, // Activity tracker
      reloadCount: 0 // Reload blocker
    }
  },

  computed: {
    isAuthenticated() {...} // Authentication check
    locale() {...} // Locale
  },

  watch: {
    locale(value) {...},
    isAuthenticated(value) {...} // Authentication check
  },

  async created() {
    const initialLocale = localStorage.getItem('locale') // Locale
    await this.loadLocaleAsync(initialLocale) // Locale
  },

  mounted() {
    EventBus.$on(MY_EVENT, this.handleMyEvent) // Event Bus registration

    this.setReloadCount() // Reload blocker
    this.blockReload() // Reload blocker

    this.activateActivityTracker() // Activity tracker
    this.resetActivityTimeout() // Activity tracker
  },

  beforeDestroy() {
    this.deactivateActivityTracker() // Activity tracker
    clearTimeout(this.userActivityTimeout) // Activity tracker
    EventBus.$off(MY_EVENT, this.handleMyEvent) // Event Bus registration
  },

  methods: {
    activateActivityTracker() {...}, // Activity tracker
    blockReload() {...}, // Reload blocker
    deactivateActivityTracker() {...}, // Activity tracker
    handleMyEvent() {...}, // Event Bus registration
    async loadLocaleAsync(selectedLocale) {...} // Locale
    redirectUser() {...} // Authentication check
    resetActivityTimeout() {...}, // Activity tracker
    setI18nLocale(locale) {...}, // Locale
    setReloadCount() {...}, // Reload blocker
    userActivityThrottler() {...}, // Activity tracker
  }
}
</script>

See how hard it is to untangle all of those? ?

Now imagine you need to make a change in one functionality (e.g. activity tracking logic). Not only do you need to know which elements are related to that logic, but even when you know, you still need to jump up and down between different component options.

Let’s use the Composition API to separate the code by logical concerns. To do that we create a single function for each logic related to a specific functionality. This is what we call a composition function.

// Activity tracking logic
function useActivityTracker() {
  const userActivityTimeout = ref(null)
  const lastUserActivityAt = ref(null)

  function activateActivityTracker() {...}
  function deactivateActivityTracker() {...}
  function resetActivityTimeout() {...}
  function userActivityThrottler() {...}

  onBeforeMount(() => {
    activateActivityTracker()
    resetActivityTimeout()
  })

  onUnmounted(() => {
    deactivateActivityTracker()
    clearTimeout(userActivityTimeout.value)
  })
}

// Reload blocking logic
function useReloadBlocker(context) {
  const reloadCount = ref(null)

  function blockReload() {...}
  function setReloadCount() {...}

  onMounted(() => {
    setReloadCount()
    blockReload()
  })
}

// Locale logic
function useLocale(context) {
  async function loadLocaleAsync(selectedLocale) {...}
  function setI18nLocale(locale) {...}

  watch(() => {
    const locale = ...
    loadLocaleAsync(locale)
  })

  // No need for a 'created' hook, all logic that runs in setup function is placed between beforeCreate and created hooks
  const initialLocale = localStorage.getItem('locale')
  loadLocaleAsync(initialLocale)
}

// Event bus listener registration
import EventBus from '@/event-bus'

function useEventBusListener(eventName, handler) {
  onMounted(() => EventBus.$on(eventName, handler))
  onUnmounted(() => EventBus.$off(eventName, handler))
}

As you can see, we can declare reactive data (ref / reactive), computed props, methods (plain functions), watchers (watch) and lifecycle hooks (onMounted / onUnmounted). Basically everything you normally use in a component.

We have two options when it comes to where to keep the code. We can leave it inside the component or extract it into a separate file. Since the Composition API is not officially there yet, there are no best practices or rules on how to deal with it. The way I see it, if the logic is tightly coupled to a specific component (i.e. it won’t be reused anywhere else), and it can’t live without the component itself, I suggest leaving it within the component. On the flip side, if it is general functionality that will likely be reused, I suggest extracting it to a separate file. However, if we want to keep it in a separate file, we need to remember to export the function from the file and import it in our component.

This is how our component will look like using newly created composition functions:

<template>
  <div id="app">
      
  </div>
</template>

<script>
export default {
  name: 'App',

  setup(props, context) {
    useEventBusListener(MY_EVENT, handleMyEvent)
    useActivityTracker()
    useReloadBlocker(context)
    useLocale(context)

    const isAuthenticated = computed(() => ...)

    watch(() => {
      if (!isAuthenticated) {...}
    })

    function handleMyEvent() {...},

    function useLocale() {...}
    function useActivityTracker() {...}
    function useEventBusListener() {...}
    function useReloadBlocker() {...}
  }
}
</script>

This gives us a single function for each logical concern. If we want to use any specific concern, we need to call the related composition function in the new setup function.

Imagine again that you need to make some change in activity tracking logic. Everything related to that functionality lives in the useActivityTracker function. Now you instantly know where to look and jump to the right place to see all the related pieces of code. Beautiful!

Extracting reusable pieces of code

In our case, the Event Bus listener registration looks like a piece of code we can use in any component that listens to events on Event Bus.

As mentioned before, we can keep the logic related to a specific functionality in a separate file. Let’s move our Event Bus listener setup into a separate file.

// composables/useEventBusListener.js
import EventBus from '@/event-bus'

export function useEventBusListener(eventName, handler) {
  onMounted(() => EventBus.$on(eventName, handler))
  onUnmounted(() => EventBus.$off(eventName, handler))
}

To use it in a component, we need to make sure we export our function (named or default) and import it in a component.

<template>
  <div id="app">
    ...
  </div>
</template>

<script>
import { useEventBusListener } from '@/composables/useEventBusListener'

export default {
  name: 'MyComponent',

  setup(props, context) {
    useEventBusListener(MY_EVENT, myEventHandled)
    useEventBusListener(ANOTHER_EVENT, myAnotherHandled)
  }
}
</script>

That’s it! We can now use that in any component we need.

Wrapping up

There is an ongoing discussion about the Composition API. This post has no intention to promote any side of the discussion. It is more about showing when it might be useful and in what cases it brings additional value.

I think it is always easier to understand the concept on a real life example like above. There are more use cases and, the more you use the new API, the more patterns you will see. This post is merely a few basic patterns to get your started.

Let’s go again through the presented use cases and see where the Composition API can be useful:

General features that can live on its own without tight coupling with any specific component

• All logic related to a specific feature in one file
• Keep it in @/composables/*.js and import it in components
• Examples: Activity Tracker, Reload Blocker, and Locale

Reusable features that are used in multiple components

• All logic related to a specific feature in one file
• Keep it in @/composables/*.js and import in components
• Examples: Event Bus listener registration, window event registration, common animation logic, common library usage

Code organization within component

• All logic related to a specific feature in one function
• Keep the code in a composition function within the component
• The code related to the same logical concern is in the same place (i.e. there’s no need to jump between data, computed, methods, lifecycle hooks, etc.)

Remember: This is all a work-in-progress!

The Vue Composition API is currently at work in progress stage and is subject to future changes. Nothing mentioned in the examples above is sure, and both syntax and use cases may change. It is intended to be shipped with Vue version 3.0. In the meantime, you can check out view-use-web for a collection of composition functions that are expected to be included in Vue 3 but can be used with the Composition API in Vue 2.

If you want to experiment with the new API you can use the @vue/composition library.

The post An Early Look at the Vue 3 Composition API in the Wild appeared first on CSS-Tricks.