Managing Vue.js State with Vuex

Vuex, while being an official package for Vue, is not built-in. You have to decide whether or not you’ll need it in your app, then install it accordingly through yarn or npm.

# Yarn
$ yarn add vuex
# NPM
$ npm install vuex --save

Then, in your app bootstrap, make sure you enable the Vuex plugin.

import Vue from 'vue';
import Vuex from 'vuex';
import App from 'App.vue';

Vue.use(Vuex);

new Vue({
  el: '#app',
  render: h => h(App)
});

To be able to take advantage of the features Vuex provides, you’ll first need to create a store. A store is essentially a global reactive object which follows the normal Vue reactivity patterns. It cannot be accessed or modified directly in order to ensure a consistent state and allow easy tracking of changes. Here’s how you create one.

export const store = new Vuex.Store({
  state: {
    safelyStoredNumber: 0
  }
});

Now, to access the store you’ll either have to import it in all of your components, or you can inject it into the root Vue instance to have it automatically injected into every other component in your app as this.$store. We’ll be using the latter method for the rest of this article.

import Vue from 'vue';
import Vuex from 'vuex';
import App from 'App.vue';
import { store } from './store.js';

Vue.use(Vuex);

new Vue({
  store,
  el: '#app',
  render: h => h(App)
});

A getter is simply a function in your store that takes a state object and returns a value from it. In your components, it can be accessed through this.$store.getters.property as a computed property, not a function. If a getter needs a parameter, it can return a second function which takes a parameter.

export const store = new Vuex.Store({
  state: {
    safelyStoredNumber: 0
  },
  getters: {
    safelyStoredNumber: state => state.safelyStoredNumber,
    storedNumberMatches(state) {
      return matchNumber => {
          return state.safelyStoredNumber === matchNumber;
      }
    }
    // Shorthand:
    // storedNumberMatches: state => matchNumber => state.safelyStoredNumbers === matchNumber
  }
});

The easy way to access getters in your component, however, is through Vuex’s mapGetters helper method. This allows you to mount getters to top-level computed properties in your component.

<template>
  <p>The safely stored number: {{safelyStoredNumber}}<p>
</template>

<script>
import { mapGetters } from 'vuex'

export default {
  computed: {
    ...mapGetters([
      // Mounts the "safelyStoredNumber" getter to the scope of your component.
      'safelyStoredNumber'
    ])
  }
}
</script>

Direct modification of state in Vuex is done by calling a function called a mutation. A mutation is passed the current state and an optional payload. The payload can be any object. Mutations must be synchronous and shouldn’t return a value. They can be used directly by running this.$store.commit(‘mutationName’, payload).

export const store = new Vuex.Store({
  state: {
    safelyStoredNumber: 0
  },
  ...
  mutations: {
    incrementStoredNumber(state) {
      state.safelyStoredNumber++;
    },
    setStoredNumber(state, newNumber) {
      // newNumber is the payload passed in.
      state.safelyStoredNumber = newNumber;
    }
  }
});

As with getters, Vuex has a convenience method for mutations in component as well, the mapMutations helper method. This allows you to mount mutations as methods in your component.

<template>
  <p>The safely stored number: {{safelyStoredNumber}}<p>
</template>

<script>
import { mapMutations } from 'vuex'

export default {
  ...
  methods: {
    ...mapMutations([
      // Mounts the "incrementStoredNumber" mutation to `this.incrementStoredNumber()`.
      'incrementStoredNumber',
      // Mounts the "setStoredNumber" mutation to `this.setStoredNumber(newNumber)`.
      'setStoredNumber'
    ])
  }
}
</script>

In more complicated apps, it’s likely that you will need to perform some asynchronous actions that modify the state. Vuex handles this with actions. They are defined on your state object as well, and are passed the entire state context, which allows them to access getters and commit mutations. They are expected (but not required) to return a promise indicating completion status. Using ES2017 async/await, you can write very terse but easy to understand async actions. Actions are used in components directly with this.$store.dispatch(‘actionName’, payload).then(response => {}).

To modify state within an action, use context.commit(‘mutationName’, payload). Multiple mutations are allowed inside an action.

import myRemoteService from './my-remote-service.js'

export const store = new Vuex.Store({
  state: {
    safelyStoredNumber: 0
  },
  ...
  actions: {
    async setNumberToRemoteValue(context) {
      // Commits the 'setStoredNumber' mutation with the value of whatever myRemoteService.getRemoteValue() resolves through a promise.
      context.commit('setStoredNumber', await myRemoteService.getRemoteValue());
      return Promise.resolve();
    },
  }
});

The Vuex convenience method for actions, (predictably named mapActions) is used in the same way as the one for mutations.

<template>
  <p>The safely stored number: {{safelyStoredNumber}}<p>
</template>

<script>
import { mapActions } from 'vuex'

export default {
  ...
  methods: {
    ...mapActions([
      // Mounts the "setNumberToRemoteValue" action to `this.setNumberToRemoteValue()`.
      'setNumberToRemoteValue',
    ])
  }
}
</script>