Whether or not to save the settings file atomically.
The path to the settings directory. Defaults to your app's user data direcory.
A custom Electron instance to use. Great for testing!
The name of the settings file that will be saved to the disk.
The number of spaces to use when stringifying the data
before saving to disk if prettify
is set to true
.
Whether or not to prettify the data when it's saved to disk.
At the basic level, a key path is the string equivalent of dot notation in JavaScript. Take the following object, for example:
const obj = {
color: {
name: 'cerulean',
code: {
rgb: [0, 179, 230],
hex: '#003BE6'
}
}
}
You can access the value of the key name
in plain
JavaScript by traversing the tree using object dot
notation, like so:
console.log(obj.color.name);
// => "cerulean"
Similarly in Electron Settings, you are reading and writing to a JSON object in a file, and a key path is just a string that points to a specific key within that object -- essentially using object dot notation in string form.
settings.get('color.name');
// => "cerulean"
Key paths need not be just strings. In fact, there are perfectly valid use-cases where you might need to access a key, but the name of the key is stored in some variable. In this case, you can specify an array of strings which can be flattened into a regular key path.
const h = 'hue';
settings.get(['color', h]);
// => undefined
Additionally, since Electron Settings uses Lodash's get() function under the hood, you can even use array syntax:
settings.get('color.code.rgb[1]');
// => 179
Using key paths, you are not limited to setting only top-level keys like you would be with LocalStorage. With Electron Settings, you can deeply nest properties like you would with any other object in JavaScript, and it just feels natural.
A SettingsObject
is an object whose property values
are of the type SettingsValue
.
SettingsValue
types are the datatypes supported by
Electron Settings. Since Electron Settings reads and
writes to a JSON file, any value you set must be a valid
JSON value. This does however mean that Date
types are
not supported.
Either simply store a numeric unix timestamp using
Date.now()
, or convert dates back into Date
types
using new Date()
:
await settings.set('user.lastLogin', new Date());
const lastLogin = await settings.get('user.lastLogin');
const lastLoginDate = new Date(lastLogin);
Gets all settings. For sync, use getSync().
A promise which resolves with all settings.
Gets the value at the given key path. For sync, use getSync().
The key path of the property.
A promise which resolves with the value at the given key path.
Gets all settings. For async, use get().
All settings.
Gets the value at the given key path. For async, use get().
The key path of the property.
The value at the given key path.
Sets all settings. For sync, use setSync().
The new settings.
A promise which resolves when the settings have been set.
Sets the value at the given key path. For sync, use setSync().
The key path of the property.
A promise which resolves when the setting has been set.
Sets all settings. For async, use set().
The new settings.
Sets the value at the given key path. For async, use set().
The key path of the property.
The value to set.
Unsets all settings. For sync, use unsetSync().
A promise which resolves when the settings have been unset.
Unsets the property at the given key path. For sync, use unsetSync().
The key path of the property.
A promise which resolves when the setting has been unset.
Returns the path to the settings file.
In general, the settings file is stored in your app's
user data directory in a file called settings.json
.
The default user data directory varies by system.
~/Library/Application\ Support/<Your App>
%APPDATA%/<Your App>
$XDG_CONFIG_HOME/<Your App>
or
~/.config/<Your App>
Although it is not recommended, you may change the name or location of the settings file using configure().
The path to the settings file.
Resets the Electron Settings configuration to defaults.
Generated using TypeDoc
Config
types contain all the configuration options for Electron Settings that can be set using configure().