- ๐พ Persistent state - persistently stores the Vuex state in your Electron app
- ๐ Easy integration - integrates perfectly with Vue and Electron as a Vuex Plugin
- ๐จ Customization - specify what parts of your Vuex state you want to persist and which mutations are allowed
- โป๏ธ Migrations - the persisted state can be easily migrated between different versions of your Electron app
- ๐ Encryption - you can optionally encrypt the storage file with a encryption key
- โ๏ธ Electron main process - access the state & commit mutations/dispatch actions from the Electron main process
This library is a wrapper around electron-store to make it work directly with Vuex and offer additional features.
npm install vuex-electron-store
Requires Electron 11 or later and currently only works with Vue 2
To use vuex-electron-store, add it as a plugin to your Vuex store:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
plugins: [
PersistedState.create()
],
// ...
})
And then initialize it in the Electron main process:
import PersistedState from 'vuex-electron-store'
PersistedState.initRenderer()
If you access the store from the main process (using
.getStoreFromRenderer()
) this is not needed
And you are done! Your Electron app now has a persistent Vuex state! ๐
You can also pass an options object to .create()
to customize the behaviour of vuex-electron-store further:
PersistedState.create({
paths: [ 'auth.user' ]
})
Here are all the options vuex-electron-store supports:
Name | Type | Description | Default |
---|---|---|---|
fileName |
string |
Name of the storage file (without extension) | vuex |
paths |
array |
An array of any paths to partially persist the state | n/a |
filter |
function |
A function which will be called on each mutation that triggers setState |
n/a |
overwrite |
boolean |
Overwrite the existing state with the persisted state directly when rehydrating | false |
storageKey |
string |
Name of the key used for the stored state object | state |
checkStorage |
boolean |
Check if the storage file is available and can be accessed | true |
dev |
boolean |
Enable development mode | false |
reducer |
function |
A function to reduce the state to persist based on the given paths | n/a |
arrayMerger |
function |
A function for merging arrays when rehydrating state | combine arrays |
resetMutation |
string |
Name of a mutation which when called will reset the persisted state | n/a |
encryptionKey |
string/Buffer/TypedArray/DataView |
Encryption key used to encrypt the storage file | n/a |
storageFileLocation |
string |
Location where the storage file should be stored | config directory |
migrations |
object |
Migration operations to perform to the persisted state whenever a version is upgraded | n/a |
ipc |
boolean |
Enable IPC communication with the main process | false |
Here are some of the more important options in a more detailed form.
You can specify different paths (i.e. parts) of you state with the paths
option. It accepts an array of paths specified using dot notation e.g. user.name
.
If no paths are given, the complete state is persisted. If an empty array is given, no state is persisted.
See Example
PersistedState.create({
paths: ['user.token']
})
Here, only the user.token
will be persisted and rehydrated.
You can limit the mutations which can persist state with the filter
function. The specified function will be called on each mutation that triggers setState
.
See Example
PersistedState.create({
filter: (name) => name === 'increment'
})
Here, only state changed by the increment
mutation will be persisted and rehydrated.
By default the the existing state will be merged using deepmerge with the persisted state. If you set overwrite
to true, the persisted state will overwrite the existing state directly when rehydrating.
See Example
PersistedState.create({
overwrite: true
})
During development it might be useful to disable persisting and rehydrating the state. You can disable this with the dev
option. When it is set to true, all changes to the state will not be persisted (regardless of the paths provided), rehydration of the state will be skipped and migrations will not be performed.
See Example
PersistedState.create({
dev: true
})
You can specify operations to perform to the persisted state whenever a version is upgraded. The migrations
object should consist of a key-value pair of 'version': handler
(the version
can also be a semver range). In the handler you can manipulate the previously persisted state (just like any other JavaScript object) before it is rehydrated.
See Example
PersistedState.create({
migrations: {
'0.1.0': (state) => {
state.debugPhase = true
},
'1.0.0': (state) => {
delete state.debugPhase
state.phase = '1.0.0'
},
'1.0.2': (state) => {
state.phase = '1.0.2'
},
'>=2.0.0': (state) => {
state.phase = '>=2.0.0'
}
}
})
The state
parameter contains the persisted state before rehydration.
You can programmatically reset the persisted state by specifying the name of a mutation as the resetMutation
option. Once you call that mutation, the entire persisted state will be deleted. You have to create a mutation by the same name, even if it doesn't do anything.
See Example
PersistedState.create({
resetMutation: 'ELECTRON_STORE_RESET'
})
You have to create a mutation by the same name, even if it doesn't do anything.:
mutations: {
ELECTRON_STORE_RESET(state) {
// Optionally do something else here
}
}
Later in a component or somewhere else:
this.$store.commit('ELECTRON_STORE_RESET')
You can optionally specify an encryption key which will be used to encrypt the storage file using the aes-256-cbc encryption algorithm. This is only secure if you don't store the key in plain text, but in a secure manner in the Node.js app. You could use node-keytar to store the encryption key securely, or deriving the key from a password entered by the user.
It might also be useful for obscurity. If a user looks through the config directory and finds the config file, since it's just a JSON file, they may be tempted to modify it. By providing an encryption key, the file will be obfuscated, which should hopefully deter any users from doing so.
See Example
PersistedState.create({
encryptionKey: 'superSecretKey'
})
Don't store the key like this if security is of concern, the encryption key would be easily found in the Electron app.
If you want to access the state or commit mutations/dispatch actions from the Electron main process, you need to enable ipc
mode.
You can then use the .getStoreFromRenderer()
method in the main process to listen for an IPC connection from the renderer. Once connected you can use the returned .commit()
and .dispatch()
methods like you would in a normal Vue Component. Calling .getState()
returns a promise containing the current Vuex state.
This can only be used with one renderer
See Example
Enable ipc
mode:
PersistedState.create({
ipc: true
})
Then in the Electron main process:
import PersistedState from 'vuex-electron-store'
const store = await PersistedState.getStoreFromRenderer()
// Commit a mutation
store.commit(type, payload, options)
// Dispatch an action
store.dispatch(type, payload, options)
// Get the current Vuex State
const state = await store.getState()
// Reset the persisted State
store.clearState()
When you use
.getStoreFromRenderer()
you don't need to call.initRenderer()
Here are a few examples to help you get started!
Before you use any of them, make sure you initialize the module in the Electron main process:
import PersistedState from 'vuex-electron-store'
PersistedState.initRenderer()
In this example the entire state will be persisted and rehydrated after a restart:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
state: {
username: ''
},
plugins: [
PersistedState.create()
],
// ...
})
In this example only part of the state will be persisted and rehydrated after a restart:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
state: {
input: ''
user: {
token: ''
}
},
plugins: [
PersistedState.create({
paths: ['user.token']
})
],
// ...
})
Here, only the user.token
will be persisted and rehydrated.
In this example we add a filter to specify which mutations can persist the updated state:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
mutations: {
// ...
increment(state) {
// mutate state
state.count++
},
decrement(state) {
// mutate state
state.count--
}
},
plugins: [
PersistedState.create({
filter: (name) => name === 'increment'
})
],
// ...
})
Here, only state changed by the increment
mutation will be persisted and rehydrated.
By default arrays from the existing state will be merged with arrays from the persisted state. You can change this behaviour by specifying a different arrayMerger
function which deepmerge will use to merge the two arrays.
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
state: {
todos: ['test1', 'test2']
},
plugins: [
PersistedState.create({
arrayMerger: (stateArray, persistedStateArray, options) => { /* ... */ }
})
],
// ...
})
Use the function below to overwrite the existing arrays with the persisted arrays:
const overwriteMerge = (stateArray, persistedStateArray, options) => persistedStateArray
If you want to overwrite the entire state, not just arrays, set the overwrite
option to true
instead.
By default the existing state will be merged with the persisted state using deepmerge. You can disable this behaviour and instead directly overwrite the existing state with the persisted state using the overwrite
option:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
plugins: [
PersistedState.create({
overwrite: true
})
],
// ...
})
Setting dev
to true will stop vuex-electron-store from persisting and rehydrating the state.
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
plugins: [
PersistedState.create({
dev: true
})
],
// ...
})
You can reset the persisted state by specifying a mutation as the resetMutation
option and then calling it:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
mutations: {
ELECTRON_STORE_RESET(state) {
// Optionally do something else here
}
},
plugins: [
PersistedState.create({
resetMutation: 'ELECTRON_STORE_RESET'
})
],
// ...
})
// Later in a component or somewhere else
this.$store.commit('ELECTRON_STORE_RESET')
You have to create a mutation by the same name, even if it doesn't do anything.
You can optionally encrypt/obfuscate the storage file by specifying an encryption key:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
plugins: [
PersistedState.create({
encryptionKey: 'superSecretKey'
})
],
// ...
})
Don't store the key like this if security is of concern, the encryption key would be easily found in the Electron app.
You can use migrations to perform operations on the persisted data whenever a version is upgraded. The migrations object should consist of a key-value pair of 'version': handler
. In the handler you can manipulate the state like any other JavaScript object:
import Vue from 'vue'
import Vuex from 'vuex'
import PersistedState from 'vuex-electron-store'
Vue.use(Vuex)
export default new Vuex.Store({
// ...
plugins: [
PersistedState.create({
migrations: {
'0.1.0': (state) => {
state.debugPhase = true
},
'1.0.0': (state) => {
delete state.debugPhase
state.phase = '1.0.0'
},
'1.0.2': (state) => {
state.phase = '1.0.2'
},
'>=2.0.0': (state) => {
state.phase = '>=2.0.0'
}
}
})
],
// ...
})
The state
parameter contains the persisted state before rehydration.
If you enable the ipc
mode you can access the state or commit mutations/dispatch actions from the Electron main process:
import PersistedState from 'vuex-electron-store'
const store = await PersistedState.getStoreFromRenderer()
// Commit a mutation
store.commit(type, payload, options)
// Dispatch an action
store.dispatch(type, payload, options)
// Get the current Vuex State
const state = await store.getState()
// Reset the persisted State
store.clearState()
When you use
.getStoreFromRenderer()
you don't need to call.initRenderer()
Issues and PRs are very welcome!
- run
yarn lint
ornpm run lint
to run eslint. - run
yarn watch
ornpm run watch
to watch for changes. - run
yarn build
ornpm run build
to produce a compiled version in thelib
folder.
- Add support for Vue 3
This project was developed by me (@betahuhn) in my free time. If you want to support me:
This library is a wrapper around the great electron-store by @sindresorhus and was inspired by vuex-electron and vuex-persistedstate.
Copyright 2021 Maximilian Schiller
This project is licensed under the MIT License - see the LICENSE file for details.