electron-store

Simple data persistence for your Electron app or module - Save and load user preferences, app state, cache, etc

Electron doesn't have a built-in way to persist user preferences and other data. This module handles that for you, so you can focus on building your app. The data is saved in a JSON file in app.getPath('userData').

You can use this module directly in both the main and renderer process.

Install

$ npm install electron-store

Requires Electron 4 or later.

Usage

const Store = require('electron-store');
const store = new Store();

store.set('unicorn', '🦄');
console.log(store.get('unicorn'));
//=> '🦄'

// Use dot-notation to access nested properties
store.set('foo.bar', true);
console.log(store.get('foo'));
//=> {bar: true}

store.delete('unicorn');
console.log(store.get('unicorn'));
//=> undefined

API

Changes are written to disk atomically, so if the process crashes during a write, it will not corrupt the existing config.

Store([options])

Returns a new instance.

options

defaults

Type: Object

Default data.

name

Type: string Default: config

Name of the storage file (without extension).

This is useful if you want multiple storage files for your app. Or if you're making a reusable Electron module that persists some data, in which case you should not use the name config.

cwd

Type: string Default: app.getPath('userData')

Storage file location. Don't specify this unless absolutely necessary!

If a relative path, it's relative to the default cwd. For example, {cwd: 'unicorn'} would result in a storage file in ~/Library/Application Support/App Name/unicorn.

encryptionKey

Type: string Buffer TypedArray DataView Default: undefined

Note that this is not intended for security purposes, since the encryption key would be easily found inside a plain-text Electron app.

Its main use is 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.

It also has the added bonus of ensuring the config file's integrity. If the file is changed in any way, the decryption will not work, in which case the store will just reset back to its default state.

When specified, the store will be encrypted using the aes-256-cbc encryption algorithm.

fileExtension

type: string Default: json

Extension of the config file.

You would usually not need this, but could be useful if you want to interact with a file with a custom file extension that can be associated with your app. These might be simple save/export/preference files that are intended to be shareable or saved outside of the app.

Instance

You can use dot-notation in a key to access nested properties.

The instance is iterable so you can use it directly in a for…of loop.

.set(key, value)

Set an item.

The value must be JSON serializable.

.set(object)

Set multiple items at once.

.get(key, [defaultValue])

Get an item or defaultValue if the item does not exist.

.has(key)

Check if an item exists.

.delete(key)

Delete an item.

.clear()

Delete all items.

.onDidChange(key, callback)

callback: (newValue, oldValue) => {}

Watches the given key, calling callback on any changes. When a key is first set oldValue will be undefined, and when a key is deleted newValue will be undefined.

Events are only triggered in the same process. So you won't get events in the main process if you trigger an event in a renderer process. See #39.

.size

Get the item count.

.store

Get all the data as an object or replace the current data with an object:

conf.store = {
	hello: 'world'
};

.path

Get the path to the storage file.

.openInEditor()

Open the storage file in the user's editor.

FAQ

• Advantages over window.localStorage

Related

• electron-util - Useful utilities for developing Electron apps and modules
• electron-debug - Adds useful debug features to your Electron app
• electron-context-menu - Context menu for your Electron app
• electron-dl - Simplified file downloads for your Electron app
• electron-unhandled - Catch unhandled errors and promise rejections in your Electron app
• electron-reloader - Simple auto-reloading for Electron apps during development
• electron-serve - Static file serving for Electron apps
• conf - Simple config handling for your app or module

License

MIT © Sindre Sorhus