node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »

vuex-persist

vuex-persist

A Typescript-ready Vuex plugin that enables you to save the state of your app to a persisted storage like Cookies or localStorage.

GitHub stars npm npm license

Build Status bitHound Overall Score bitHound Dependencies codebeat badge Codacy Badge Code Climate codecov

Features

  • Automatically save store on mutation.
  • Choose which mutations trigger store save, and which don't, using filter function
  • Works perfectly with modules in store
  • Ability to save partial store, using a reducer function
  • Automatically restores store when app loads
  • You can create mulitple VuexPersistence instances if you want to -
    • Save some parts of the store to localStorage, some to sessionStorage
    • Trigger saving to localStorage on data download, saving to cookies on authentication result

Compatibility

  • VueJS - v2.0 and above
  • Vuex - v2.1 and above

Installation

npm install --save vuex-persist

or

yarn add vuex-persist

Usage

Steps

Import it

import VuexPersistence from 'vuex-persist'

Create an object

const vuexLocal = new VuexPersistence({
    storage: window.localStorage
})

Use it as Vue plugin. (in typescript)

const store = new Vuex.Store<State>({
  state: { ... },
  mutations: { ... },
  actions: { ... },
  plugins: [vuexLocal.plugin]
})

(or in Javascript)

const store = {
  state: { ... },
  mutations: { ... },
  actions: { ... },
  plugins: [vuexLocal.plugin]
}

Constructor Parameters -

When creating the VuexPersistence object, we pass an options object of type PersistOptions. Here are the properties, and what they mean -

Property Type Description
key string The key to store the state in the storage
Default: 'vuex'
storage Storage (Web API) localStorage, sessionStorage, localforage or your custom Storage object.
Must implement getItem, setItem, clear etc.
Default: window.localStorage
saveState function
(key, state[, storage])
If not using storage, this custom function handles
saving state to persistence
restoreState function
(key[, storage]) => state
If not using storage, this custom function handles
retrieving state from storage
reducer function
(state) => object
State reducer. reduces state to only those values you want to save.
By default, saves entire state
filter function
(mutation) => boolean
Mutation filter. Look at mutation.type and return true
for only those ones which you want a persistence write to be triggered for.
Default returns true for all mutations
modules string[] List of modules you want to persist. (Do not write your own reducer if you want to use this)

Examples

Simple

Quick example -

import Vue from 'vue'
import Vuex from 'vuex'
import VuexPersistence from 'vuex-persist'
 
 
Vue.use(Vuex)
 
const store = new Vuex.Store<State>({
  state: {
    user: {name: 'Arnav'},
    navigation: {path: '/home'}
  },
  plugins: [(new VuexPersistence()).plugin]
})
 
export default store

Detailed

Here is an example store that has 2 modules, user and navigation We are going to save user details into a Cookie (using js-cookie) And, we will save the navigation state into localStorage whenever a new item is added to nav items. So you can use multiple VuexPersistence instances to store different parts of your Vuex store into different storage providers.

import Vue from 'vue'
import Vuex, {Payload, Store} from 'vuex'
import VuexPersistence from 'vuex-persist'
import Cookies from 'js-cookie'
import {module as userModule, UserState} from './user'
import navModule, {NavigationState} from './navigation'
 
export interface State {
  user: UserState,
  navigation: NavigationState
}
 
 
Vue.use(Vuex)
 
const vuexCookie = new VuexPersistence<State, Payload>({
  restoreState: (key, storage) => Cookies.getJSON(key),
  saveState: (key, state, storage) => Cookies.set(key, state, {
    expires: 3
  }),
  modules: ['user'], //only save user module
  filter: (mutation) => (mutation.type == 'logIn' || mutation.type == 'logOut')
})
const vuexLocal = new VuexPersistence<State, Payload> ({
  storage: window.localStorage,
  reducer: state => ({navigation: state.navigation}), //only save navigation module
  filter: mutation => (mutation.type == 'addNavItem')
})
 
const store = new Vuex.Store<State>({
  modules: {
    user: userModule,
    navigation: navModule
  },
  plugins: [vuexCookie.plugin, vuexLocal.plugin]
})
 
export default store
 

Support Strict Mode

This now supports Vuex strict mode (Keep in mind, NOT to use strict mode in production) In strict mode, we cannot use store.replaceState so instead we use a mutation

You'll need to keep in mind to add the RESTORE_MUTATION to your mutations See example below

To configure with strict mode support -

import Vue from 'vue'
import Vuex, {Payload, Store} from 'vuex'
import VuexPersistence from 'vuex-persist'
 
const vuexPersist = new VuexPersistence<any, any>({
  strictMode: true, // This **MUST** be set to true
  storage: localStorage,
  reducer: (state) => ({ dog: state.dog }),
  filter: (mutation) => (mutation.type === 'dogBark')
})
 
const store = new Vuex.Store<State>({
  strict: true, // This makes the Vuex store strict
  state: {
    user: {
      name: 'Arnav'
    },
    foo: {
      bar: 'baz'
    }
  },
  mutations: {
    RESTORE_MUTATION: vuexPersist.RESTORE_MUTATION // this mutation **MUST** be named "RESTORE_MUTATION"
  },
  plugins: [vuexPersist.plugin]
})

Some of the most popular ways to persist your store would be -

  • js-cookie to use browser Cookies
  • window.localStorage (remains, across PC reboots, untill you clear browser data)
  • window.sessionStorage (vanishes when you close browser tab)
  • localForage Uses IndexedDB from the browser