Awesome
electron-json-storage
Easily write and read user settings in Electron apps
Electron lacks an easy way to persist and read user settings for your application. electron-json-storage
implements an API somewhat similar to localStorage to write and read JSON objects to/from the operating system application data directory, as defined by app.getPath('userData')
.
Related modules:
Installation
Install electron-json-storage
by running:
$ npm install --save electron-json-storage
You can require this module from either the main or renderer process (with and without remote
).
Running on Electron >10 renderer processes
When loaded in renderer processes, this module will try to make use of
electron.remote
in order to fetch the userData
path.
Electron 10 now defaults enableRemoteModule
to
false,
which means that electron-json-storage
will be able to calculate a data path by default.
The solution is to manually call storage.setDataPath()
before reading or
writing any values or setting enableRemoteModule
to true
.
Documentation
- storage
- .getDefaultDataPath() ⇒ <code>String</code> | <code>Null</code>
- .setDataPath(directory)
- .getDataPath() ⇒ <code>String</code>
- .get(key, [options], callback)
- .getSync(key, [options])
- .getMany(keys, [options], callback)
- .getAll([options], callback)
- .set(key, json, [options], callback)
- .has(key, [options], callback)
- .keys([options], callback)
- .remove(key, [options], callback)
- .clear([options], callback)
<a name="module_storage.getDefaultDataPath"></a>
storage.getDefaultDataPath() ⇒ <code>String</code> | <code>Null</code>
This function will return null
when running in the
renderer process without support for the remote
IPC
mechanism. You have to explicitly set a data path using
.setDataPath()
in these cases.
Kind: static method of <code>storage</code>
Summary: Get the default data path
Returns: <code>String</code> | <code>Null</code> - default data path
Access: public
Example
const defaultDataPath = storage.getDefaultDataPath()
<a name="module_storage.setDataPath"></a>
storage.setDataPath(directory)
The default value will be used if the directory is undefined.
Kind: static method of <code>storage</code>
Summary: Set current data path
Access: public
Param | Type | Description |
---|---|---|
directory | <code>String</code> | <code>Undefined</code> | directory |
Example
const os = require('os');
const storage = require('electron-json-storage');
storage.setDataPath(os.tmpdir());
<a name="module_storage.getDataPath"></a>
storage.getDataPath() ⇒ <code>String</code>
Returns the current data path. It defaults to a directory called
"storage" inside Electron's userData
path.
Kind: static method of <code>storage</code>
Summary: Get current user data path
Returns: <code>String</code> - the user data path
Access: public
Example
const storage = require('electron-json-storage');
const dataPath = storage.getDataPath();
console.log(dataPath);
<a name="module_storage.get"></a>
storage.get(key, [options], callback)
If the key doesn't exist in the user data, an empty object is returned.
Also notice that the .json
extension is added automatically, but it's
ignored if you pass it yourself.
Passing an extension other than .json
will result in a file created
with both extensions. For example, the key foo.data
will result in a file
called foo.data.json
.
Kind: static method of <code>storage</code>
Summary: Read user data
Access: public
Param | Type | Description |
---|---|---|
key | <code>String</code> | key |
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
callback | <code>function</code> | callback (error, data) |
Example
const storage = require('electron-json-storage');
storage.get('foobar', function(error, data) {
if (error) throw error;
console.log(data);
});
<a name="module_storage.getSync"></a>
storage.getSync(key, [options])
See .get()
.
Kind: static method of <code>storage</code>
Summary: Read user data (sync)
Access: public
Param | Type | Description |
---|---|---|
key | <code>String</code> | key |
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
Example
const storage = require('electron-json-storage');
var data = storage.getSync('foobar');
console.log(data);
<a name="module_storage.getMany"></a>
storage.getMany(keys, [options], callback)
This function returns an object with the data of all the passed keys. If one of the keys doesn't exist, an empty object is returned for it.
Kind: static method of <code>storage</code>
Summary: Read many user data keys
Access: public
Param | Type | Description |
---|---|---|
keys | <code>Array.<String></code> | keys |
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
callback | <code>function</code> | callback (error, data) |
Example
const storage = require('electron-json-storage');
storage.getMany([ 'foobar', 'barbaz' ], function(error, data) {
if (error) throw error;
console.log(data.foobar);
console.log(data.barbaz);
});
<a name="module_storage.getAll"></a>
storage.getAll([options], callback)
This function returns an empty object if there is no data to be read.
Kind: static method of <code>storage</code>
Summary: Read all user data
Access: public
Param | Type | Description |
---|---|---|
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
callback | <code>function</code> | callback (error, data) |
Example
const storage = require('electron-json-storage');
storage.getAll(function(error, data) {
if (error) throw error;
console.log(data);
});
<a name="module_storage.set"></a>
storage.set(key, json, [options], callback)
Kind: static method of <code>storage</code>
Summary: Write user data
Access: public
Param | Type | Description |
---|---|---|
key | <code>String</code> | key |
json | <code>Object</code> | json object |
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
[options.validate] | <code>String</code> | validate writes by reading the data back |
[options.prettyPrinting] | <code>boolean</code> | adds line breaks and spacing to the written data |
callback | <code>function</code> | callback (error) |
Example
const storage = require('electron-json-storage');
storage.set('foobar', { foo: 'bar' }, function(error) {
if (error) throw error;
});
<a name="module_storage.has"></a>
storage.has(key, [options], callback)
Kind: static method of <code>storage</code>
Summary: Check if a key exists
Access: public
Param | Type | Description |
---|---|---|
key | <code>String</code> | key |
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
callback | <code>function</code> | callback (error, hasKey) |
Example
const storage = require('electron-json-storage');
storage.has('foobar', function(error, hasKey) {
if (error) throw error;
if (hasKey) {
console.log('There is data stored as `foobar`');
}
});
<a name="module_storage.keys"></a>
storage.keys([options], callback)
Kind: static method of <code>storage</code>
Summary: Get the list of saved keys
Access: public
Param | Type | Description |
---|---|---|
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
callback | <code>function</code> | callback (error, keys) |
Example
const storage = require('electron-json-storage');
storage.keys(function(error, keys) {
if (error) throw error;
for (var key of keys) {
console.log('There is a key called: ' + key);
}
});
<a name="module_storage.remove"></a>
storage.remove(key, [options], callback)
Notice this function does nothing, nor throws any error if the key doesn't exist.
Kind: static method of <code>storage</code>
Summary: Remove a key
Access: public
Param | Type | Description |
---|---|---|
key | <code>String</code> | key |
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
callback | <code>function</code> | callback (error) |
Example
const storage = require('electron-json-storage');
storage.remove('foobar', function(error) {
if (error) throw error;
});
<a name="module_storage.clear"></a>
storage.clear([options], callback)
Kind: static method of <code>storage</code>
Summary: Clear all stored data in the current user data path
Access: public
Param | Type | Description |
---|---|---|
[options] | <code>Object</code> | options |
[options.dataPath] | <code>String</code> | data path |
callback | <code>function</code> | callback (error) |
Example
const storage = require('electron-json-storage');
storage.clear(function(error) {
if (error) throw error;
});
Support
If you're having any problem, please raise an issue on GitHub and we'll be happy to help.
Tests
Run the test suite by doing:
$ npm test
Contribute
- Issue Tracker: github.com/electron-userland/electron-json-storage/issues
- Source Code: github.com/electron-userland/electron-json-storage
Before submitting a PR, please make sure that you include tests, and that jshint runs without any warning:
$ npm run-script lint
License
The project is licensed under the MIT license.