vuex-module-decorators

Detailed Guide: https://championswimmer.in/vuex-module-decorators/

Typescript/ES7 Decorators to make Vuex modules a breeze

Patrons

While I have a day job and I really maintain open source libraries for fun, any sponsors are extremely graciously thanked for their contributions, and goes a long way ???? ❤️

• Thomas Woo

CHANGELOG

• There are major type-checking changes (could be breaking) in v0.9.7

• There are major usage improvements (non backwards compatible) in 0.8.0

Please check CHANGELOG

Examples

Read the rest of the README to figure out how to use, or if you readily want to jump into a production codebase and see how this is used, you can check out -

• https://github.com/Armour/vue-typescript-admin-template
• https://github.com/xieguangcai/vue-order-admin
• https://github.com/coding-blocks-archives/realworld-vue-typescript

Installation

1npm install -D vuex-module-decorators

Babel 6/7

NOTE This is not necessary for vue-cli@3 projects, since @vue/babel-preset-app already includes this plugin

1. You need to install babel-plugin-transform-decorators

TypeScript

1. set experimentalDecorators to true
2. For reduced code with decorators, set importHelpers: true in tsconfig.json
3. (only for TypeScript 2) set emitHelpers: true in tsconfig.json

Configuration

Using with target: es5

NOTE Since version 0.9.3 we distribute as ES5, so this section is applicable only to v0.9.2 and below

This package generates code in es2015 format. If your Vue project targets ES6 or ES2015 then you need not do anything. But in case your project uses es5 target (to support old browsers), then you need to tell Vue CLI / Babel to transpile this package.

1// in your vue.config.js
2module.exports = {
3  /* ... other settings */
4  transpileDependencies: ['vuex-module-decorators']
5}

Usage

The conventional old & boring way

Remember how vuex modules used to be made ?

1const moduleA = {
2  state: { ... },
3  mutations: { ... },
4  actions: { ... },
5  getters: { ... }
6}
7
8const moduleB = {
9  state: { ... },
10  mutations: { ... },
11  actions: { ... }
12}
13
14const store = new Vuex.Store({
15  modules: {
16    a: moduleA,
17    b: moduleB
18  }
19})

Hello Decorators !

Well not anymore. Now you get better syntax. Inspired by vue-class-component

1import { Module, VuexModule, Mutation, Action } from 'vuex-module-decorators'
2
3@Module
4export default class Counter2 extends VuexModule {
5  count = 0
6
7  @Mutation
8  increment(delta: number) {
9    this.count += delta
10  }
11  @Mutation
12  decrement(delta: number) {
13    this.count -= delta
14  }
15
16  // action 'incr' commits mutation 'increment' when done with return value as payload
17  @Action({ commit: 'increment' })
18  incr() {
19    return 5
20  }
21  // action 'decr' commits mutation 'decrement' when done with return value as payload
22  @Action({ commit: 'decrement' })
23  decr() {
24    return 5
25  }
26}

async MutationAction === magic

Want to see something even better ?

1import { Module, VuexModule, MutationAction } from 'vuex-module-decorators'
2import { ConferencesEntity, EventsEntity } from '@/models/definitions'
3
4@Module
5export default class HGAPIModule extends VuexModule {
6  conferences: Array<ConferencesEntity> = []
7  events: Array<EventsEntity> = []
8
9  // 'events' and 'conferences' are replaced by returned object
10  // whose shape must be `{events: [...], conferences: [...] }`
11  @MutationAction({ mutate: ['events', 'conferences'] })
12  async fetchAll() {
13    const response: Response = await getJSON('https://hasgeek.github.io/events/api/events.json')
14    return response
15  }
16}

Automatic getter detection

1@Module
2class MyModule extends VuexModule {
3  wheels = 2
4
5  @Mutation
6  incrWheels(extra) {
7    this.wheels += extra
8  }
9
10  get axles() {
11    return this.wheels / 2
12  }
13}

this is turned into the equivalent

1const module = {
2  state: { wheels: 2 },
3  mutations: {
4    incrWheels(state, extra) {
5      state.wheels += extra
6    }
7  },
8  getters: {
9    axles: (state) => state.wheels / 2
10  }
11}

Putting into the store

Use the modules just like you would earlier

1import Vue from 'nativescript-vue'
2import Vuex, { Module } from 'vuex'
3
4import counter from './modules/Counter2'
5import hgapi from './modules/HGAPIModule'
6
7Vue.use(Vuex)
8
9const store = new Vuex.Store({
10  state: {},
11  modules: {
12    counter,
13    hgapi
14  }
15})

Module re-use, use with NuxtJS

If you need to support module reuse or to use modules with NuxtJS, you can have a state factory function generated instead of a static state object instance by using stateFactory option to @Module, like so:

1@Module({ stateFactory: true })
2class MyModule extends VuexModule {
3  wheels = 2
4
5  @Mutation
6  incrWheels(extra) {
7    this.wheels += extra
8  }
9
10  get axles() {
11    return this.wheels / 2
12  }
13}

this is turned into the equivalent

1const module = {
2  state() {
3    return { wheels: 2 }
4  },
5
6  mutations: {
7    incrWheels(state, extra) {
8      state.wheels += extra
9    }
10  },
11  getters: {
12    axles: (state) => state.wheels / 2
13  }
14}

Dynamic Modules

Vuex allows us to register modules into store at runtime after store is constructed. We can do the following to create dynamic modules

1interface StoreType {
2  mm: MyModule
3}
4// Declare empty store first
5const store = new Vuex.Store<StoreType>({})
6
7// Create module later in your code (it will register itself automatically)
8// In the decorator we pass the store object into which module is injected
9// NOTE: When you set dynamic true, make sure you give module a name
10@Module({ dynamic: true, store: store, name: 'mm' })
11class MyModule extends VuexModule {
12  count = 0
13
14  @Mutation
15  incrCount(delta) {
16    this.count += delta
17  }
18}

If you would like to preserve the state e.g when loading in the state from vuex-persist

1...
2
3-- @Module({ dynamic: true, store: store, name: 'mm' })
4++ @Module({ dynamic: true, store: store, name: 'mm', preserveState: true })
5class MyModule extends VuexModule {
6
7...

Or when it doesn't have a initial state and you load the state from the localStorage

1...
2
3-- @Module({ dynamic: true, store: store, name: 'mm' })
4++ @Module({ dynamic: true, store: store, name: 'mm', preserveState: localStorage.getItem('vuex') !== null })
5class MyModule extends VuexModule {
6
7...

Accessing modules with NuxtJS

There are many possible ways to construct your modules. Here is one way for drop-in use with NuxtJS (you simply need to add your modules to ~/utils/store-accessor.ts and then just import the modules from ~/store):

~/store/index.ts:

1import { Store } from 'vuex'
2import { initialiseStores } from '~/utils/store-accessor'
3const initializer = (store: Store<any>) => initialiseStores(store)
4export const plugins = [initializer]
5export * from '~/utils/store-accessor'

~/utils/store-accessor.ts:

1import { Store } from 'vuex'
2import { getModule } from 'vuex-module-decorators'
3import example from '~/store/example'
4
5let exampleStore: example
6
7function initialiseStores(store: Store<any>): void {
8  exampleStore = getModule(example, store)
9}
10
11export { initialiseStores, exampleStore }

Now you can access stores in a type-safe way by doing the following from a component or page - no extra initialization required.

1import { exampleStore } from '~/store'
2...
3someMethod() {
4  return exampleStore.exampleGetter
5}

Using the decorators with ServerSideRender

When SSR is involved the store is recreated on each request. Every time the module is accessed using getModule function the current store instance must be provided and the module must be manually registered to the root store modules

Example

1// store/modules/MyStoreModule.ts
2import { Module, VuexModule, Mutation } from 'vuex-module-decorators'
3
4@Module({
5  name: 'modules/MyStoreModule',
6  namespaced: true,
7  stateFactory: true,
8})
9export default class MyStoreModule extends VuexModule {
10  public test: string = 'initial'
11
12  @Mutation
13  public setTest(val: string) {
14    this.test = val
15  }
16}
17
18
19// store/index.ts
20import Vuex from 'vuex'
21import MyStoreModule from '~/store/modules/MyStoreModule'
22
23export function createStore() {
24  return new Vuex.Store({
25    modules: {
26      MyStoreModule,
27    }
28  })
29}
30
31// components/Random.tsx
32import { Component, Vue } from 'vue-property-decorator';
33import { getModule } from 'vuex-module-decorators';
34import MyStoreModule from '~/store/modules/MyStoreModule'
35
36@Component
37export default class extends Vue {
38    public created() {
39        const MyModuleInstance = getModule(MyStoreModule, this.$store);
40        // Do stuff with module
41        MyModuleInstance.setTest('random')
42    }
43}

Configuration

There is a global configuration object that can be used to set options across the whole module:

1import { config } from 'vuex-module-decorators'
2// Set rawError to true by default on all @Action decorators
3config.rawError = true