Features

• 💾 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.

🚀 Get started

1npm install vuex-electron-store-vue3

Requires Electron 26 or later and works with Vue 3

📚 Usage

To use vuex-electron-store-vue3, add it as a plugin to your Vuex store:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	plugins: [
11		PersistedState.create()
12	],
13	// ...
14})

And then initialize it in the Electron main process:

1import PersistedState from 'vuex-electron-store-vue3'
2
3PersistedState.initRenderer()

If you access the store from the main process (using .getStoreFromRenderer(ipcMain)) this is not needed

And you are done! Your Electron app now has a persistent Vuex state! 🎉

⚙️ Options

You can also pass an options object to .create() to customize the behaviour of vuex-electron-store-vue3 further:

1PersistedState.create({
2	paths: [ 'auth.user' ]
3})

🛠️ Configuration

Here are some of the more important options in a more detailed form.

Paths

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.

1PersistedState.create({
2	paths: ['user.token']
3})

Filter

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.

1PersistedState.create({
2	filter: (name) => name === 'increment'
3})

Overwrite

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.

1PersistedState.create({
2	overwrite: true
3})

Development Mode

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.

1PersistedState.create({
2	dev: true
3})

Migrations

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.

1PersistedState.create({
2	migrations: {
3		'0.1.0': (state) => {
4			state.debugPhase = true
5		},
6		'1.0.0': (state) => {
7			delete state.debugPhase
8			state.phase = '1.0.0'
9		},
10		'1.0.2': (state) => {
11			state.phase = '1.0.2'
12		},
13		'>=2.0.0': (state) => {
14			state.phase = '>=2.0.0'
15		}
16	}
17})

Reset Mutation

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.

1PersistedState.create({
2	resetMutation: 'ELECTRON_STORE_RESET'
3})

1mutations: {
2	ELECTRON_STORE_RESET(state) {
3		// Optionally do something else here
4	}
5}	

1this.$store.commit('ELECTRON_STORE_RESET')

Encryption

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.

1PersistedState.create({
2	encryptionKey: 'superSecretKey'
3})

IPC Mode

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(ipcMain) 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

1import { ipcRenderer } from 'electron';
2
3PersistedState.create({
4	ipc: true
5}, ipcRenderer)

1import PersistedState from 'vuex-electron-store-vue3'
2import { ipcMain } from 'electron'
3
4const store = await PersistedState.getStoreFromRenderer(ipcMain)
5
6// Commit a mutation
7store.commit(type, payload, options)
8
9// Dispatch an action
10store.dispatch(type, payload, options)
11
12// Get the current Vuex State
13const state = await store.getState()
14
15// Reset the persisted State
16store.clearState()

📖 Examples

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:

1import PersistedState from 'vuex-electron-store-vue3'
2
3PersistedState.initRenderer()

Basic Example

In this example the entire state will be persisted and rehydrated after a restart:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	state: {
11		username: ''
12	},
13	plugins: [
14		PersistedState.create()
15	],
16	// ...
17})

Only partially persist state

In this example only part of the state will be persisted and rehydrated after a restart:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	state: {
11		input: ''
12		user: {
13			token: ''
14		}
15	},
16	plugins: [
17		PersistedState.create({
18			paths: ['user.token']
19		})
20	],
21	// ...
22})

Here, only the user.token will be persisted and rehydrated.

Filter mutations

In this example we add a filter to specify which mutations can persist the updated state:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	mutations: {
11		// ...
12		increment(state) {
13			// mutate state
14			state.count++
15		},
16		decrement(state) {
17			// mutate state
18			state.count--
19		}
20	},
21	plugins: [
22		PersistedState.create({
23			filter: (name) => name === 'increment'
24		})
25	],
26	// ...
27})

Here, only state changed by the increment mutation will be persisted and rehydrated.

Merging arrays

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.

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	state: {
11		todos: ['test1', 'test2']
12	},
13	plugins: [
14		PersistedState.create({
15			arrayMerger: (stateArray, persistedStateArray, options) => { /* ... */ }
16		})
17	],
18	// ...
19})

Use the function below to overwrite the existing arrays with the persisted arrays:

1const overwriteMerge = (stateArray, persistedStateArray, options) => persistedStateArray

If you want to overwrite the entire state, not just arrays, set the overwrite option to true instead.

Overwriting the existing state

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:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	plugins: [
11		PersistedState.create({
12			overwrite: true
13		})
14	],
15	// ...
16})

During development

Setting dev to true will stop vuex-electron-store-vue3 from persisting and rehydrating the state.

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	plugins: [
11		PersistedState.create({
12			dev: true
13		})
14	],
15	// ...
16})

Reset Mutation

You can reset the persisted state by specifying a mutation as the resetMutation option and then calling it:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	mutations: {
11		ELECTRON_STORE_RESET(state) {
12			// Optionally do something else here
13		}
14	},
15	plugins: [
16		PersistedState.create({
17			resetMutation: 'ELECTRON_STORE_RESET'
18		})
19	],
20	// ...
21})
22
23// Later in a component or somewhere else
24this.$store.commit('ELECTRON_STORE_RESET')

You have to create a mutation by the same name, even if it doesn't do anything.

Encrypting the storage file

You can optionally encrypt/obfuscate the storage file by specifying an encryption key:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	plugins: [
11		PersistedState.create({
12			encryptionKey: 'superSecretKey'
13		})
14	],
15	// ...
16})

Don't store the key like this if security is of concern, the encryption key would be easily found in the Electron app.

Migration between versions

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:

1import Vue from 'vue'
2import Vuex from 'vuex'
3
4import PersistedState from 'vuex-electron-store-vue3'
5
6Vue.use(Vuex)
7
8export default new Vuex.Store({
9	// ...
10	plugins: [
11		PersistedState.create({
12			migrations: {
13				'0.1.0': (state) => {
14					state.debugPhase = true
15				},
16				'1.0.0': (state) => {
17					delete state.debugPhase
18					state.phase = '1.0.0'
19				},
20				'1.0.2': (state) => {
21					state.phase = '1.0.2'
22				},
23				'>=2.0.0': (state) => {
24					state.phase = '>=2.0.0'
25				}
26			}
27		})
28	],
29	// ...
30})

The state parameter contains the persisted state before rehydration.

Access the store from the Electron main process

If you enable the ipc mode you can access the state or commit mutations/dispatch actions from the Electron main process:

1import PersistedState from 'vuex-electron-store-vue3'
2import { ipcMain } from 'electron';
3
4const store = await PersistedState.getStoreFromRenderer(ipcMain)
5
6// Commit a mutation
7store.commit(type, payload, options)
8
9// Dispatch an action
10store.dispatch(type, payload, options)
11
12// Get the current Vuex State
13const state = await store.getState()
14
15// Reset the persisted State
16store.clearState()

When you use .getStoreFromRenderer(ipcMain) you don't need to call .initRenderer()

💻 Development

Issues and PRs are very welcome!

• run yarn lint or npm run lint to run eslint.
• run yarn watch or npm run watch to watch for changes.
• run yarn build or npm run build to produce a compiled version in the lib folder.

❔ About

This project was originally developed by (@betahuhn) in their free time, and has been updated to work with Vue3 by (@elliottcooper) on behalf of (Singular Health).

Credit

This library is a wrapper around the great electron-store by @sindresorhus and was inspired by vuex-electron and vuex-persistedstate. This project was originally developed by (@betahuhn).

📄 License

Copyright 2023 Elliott Cooper (Singular Health)

This project is licensed under the MIT License - see the LICENSE file for details.