electron-store

What is electron-store?

The electron-store npm package is a simple and efficient way to manage persistent user data in Electron applications. It provides a straightforward API for reading and writing JSON data, making it easy to store settings, preferences, and other types of data.

What are electron-store's main functionalities?

Basic Usage

This feature allows you to set, get, and delete key-value pairs in the store. It's useful for storing simple settings or preferences.

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

// Set a value
store.set('unicorn', '🦄');

// Get a value
console.log(store.get('unicorn'));
//=> '🦄'

// Delete a value
store.delete('unicorn');

Default Values

You can define default values for your store. These values will be used if no other value is set for the given key.

const Store = require('electron-store');
const store = new Store({
  defaults: {
    foo: 'bar'
  }
});

console.log(store.get('foo'));
//=> 'bar'

Schema Validation

You can define a schema to validate the data being stored. This ensures that the data conforms to the expected format and constraints.

const Store = require('electron-store');
const store = new Store({
  schema: {
    foo: {
      type: 'string',
      maxLength: 10,
      default: 'bar'
    }
  }
});

store.set('foo', 'baz');
console.log(store.get('foo'));
//=> 'baz'

Encryption

You can encrypt the data stored in the store by providing an encryption key. This adds a layer of security to sensitive data.

const Store = require('electron-store');
const store = new Store({
  encryptionKey: 'mySecretEncryptionKey'
});

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

Other packages similar to electron-store

conf

The 'conf' package is similar to electron-store in that it provides a simple way to manage configuration data. It supports schema validation, encryption, and default values. However, it is not specifically designed for Electron and can be used in any Node.js application.

lowdb

The 'lowdb' package is a small local JSON database for Node.js. It provides a simple API for reading and writing JSON data, similar to electron-store. However, it is more flexible and can be used for more complex data structures and queries.

node-persist

The 'node-persist' package is a simple, zero-dependency, key-value storage library for Node.js. It provides similar functionality to electron-store, including support for JSON data and encryption. However, it does not include schema validation or default values.

README

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

Type: Object

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.

clearInvalidConfig

Type: boolean
Default: true

The config is cleared if reading the config file causes a SyntaxError. This is a good default, as the config file is not intended to be hand-edited, so it usually means the config is corrupt and there's nothing the user can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be more useful to throw an error when the config is invalid instead of clearing. Disabling this option will make it throw a SyntaxError on invalid config instead of clearing.

serialize

Type: Function
Default: value => JSON.stringify(value, null, '\t')

Function to serialize the config object to a UTF-8 string when writing the config file.

You would usually not need this, but it could be useful if you want to use a format other than JSON.

deserialize

Type: Function
Default: JSON.parse

Function to deserialize the config object from a UTF-8 string when reading the config file.

You would usually not need this, but it could be useful if you want to use a format other than JSON.

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. Trying to set the type undefined, function, or symbol will result in a TypeError.

.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

Can I use YAML or another serialization format?

The serialize and deserialize options can be used to customize the format of the config file, as long as the representation is compatible with utf8 encoding.

Example using YAML:

const Store = require('electron-store');
const yaml = require('js-yaml');

const store = new Store({
	fileExtension: 'yaml',
	serialize: yaml.safeDump,
	deserialize: yaml.safeLoad
});

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