An simple way to store user settings in Node.js or Electron apps
> Cross-platform settings and configuration store for Node.js. A great choice for CLI apps that need to persist user data. Also has dedicated support for Electron.
- Simple but powerful API
- Support for apps with and without Electron
- Works on Windows, macOS, Linux & *ix
- Live-reloading of changes to the settings file
- Setting default values in bulk or for individual keys
- Temporarily overriding settings without saving them
- No additional dependencies
package.json or install it via the command-line:npm i --save settings-store``javascript
const settings = require("settings-store")
//Initializing is optional when using Electron
settings.init({
appName: "Foo", //required,
publisherName: "Bar", //optional
reverseDNS: "com.bar.foo" //required for macOS
})
let foo = settings.value("foo", 0)
// foo hasn’t been set before and will be: 0
settings.setValue("foo", 1)
let updatedFoo = settings.value("foo", 0)
// updatedFoo will be: 1
`
You can also use nested key paths by either using dot notation or passing them as an array:
`javascript
let name = {first: "Jane", last: "Doe"}
settings.setValue("name", name)
let firstName = settings.value("name.first")
// firstName will be: "Jane"
let lastName = settings.value(["name", "last"])
// lastName will be: "Doe"
settings.setValue("name.first", "John")
let updatedName = settings.value("name")
// name will be: {first: "John", last: "Doe"}
`
:
`javascript
let foo = {bar: "foo", foo: "bar"}
settings.setValue("foo", foo)settings.delete("foo.bar")
let updatedFoo = settings.value("foo")
// updatedFoo will be: {foo: "bar"}
`
If the given key or key path doesn’t exist, will not
throw an error.Merging nested properties
When working with nested properties, you can choose whether to merge them with previous values or not by using settings.setValue(key, value, merge=false):
`javascript
let foo = {bar: "foo", foo: "bar"}
settings.setValue("foo", foo)
let buzz = {buzz: "fizz", fizz: "buzz"}//With merging
settings.setValue("foo", buzz, true)
let merged = settings.value("foo")
// merged will be: {bar: "foo", foo: "bar", buzz: "fizz", fizz: "buzz"}
//Without merging
settings.setValue("foo", buzz, false)
let unmerged = settings.value("foo")
// unmerged will be: {buzz: "fizz", fizz: "buzz"}
`Setting default values
You can use when retrieving a value if you want to use a default value in case no other value has been set for key yet.Alternatively, you can also use
settings.loadDefaults(filename) or settings.setDefaults(settings):
`javascript
settings.setDefaults({
name: {
first: "Jane",
last: "Doe"
}
})let firstName = settings.value("name.first")
// name.first hasn’t been set yet and will default to: "Jane"
`Default values will not be stored to your settings file and existing values in the settings file will take precedence over previously set defaults.
Using overrides
If you want to temporarily override some of your user’s settings, you can use . Overridden values will take precedence over both defaults and values set with settings.setValue(key, value) but won’t be stored to the settings file.`javascript
settings.setValue("foo", "bar")
settings.override("foo", "baz")
let foo = settings.value("foo")
// foo will be: "baz"
`This can be especially handy if you want to override settings with values from environment variables.
Retrieving/clearing all settings
If you want to retrieve all settings, you can use . This will give you the complete settings store, ignoring overrides and defaults.
Clearing all settings can be achieved with settings.clear(). This will delete all properties stored with settings.setValue(key, value). Overrides and defaults will not be reset.Configuring settings-store
settings-store needs very little configuration. Simply call settings.init(opts) with your desired options before otherwise using the module.$3
If you are using Electron, your settings file will be stored in the Electron userData path (see Electron docs for more information). In this case, no configuration is required at all.$3
For applications that do not use Electron, you need to provide your application name and the reverse-DNS string and settings-store will create a settings file in a folder adequate for the user’s operating system:
`javascript
/Required configuration when not using Electron/
const settings = require("settings-store")
const settingsOpts = {
appName: "Foo", //required,
publisherName: "Bar", //optional
reverseDNS: "com.bar.foo" //required for macOS
}
settings.init(settingsOpts)
`$3
- Object | Boolean, default true
Use this to explicitly pass your object. If you want to explicitly enable or disable automatic Electron detection, you can set electronApp to true or false.
- enableReloading Boolean, default: true
Enable or disable reloading the settings file if it has been changed outside of the application
- String
Use this to override the automatically generated path of your settings fileStorable types
You can store the following types with settings-store:-
Array
-
-
-
- will be considered nested properties that can have the same types for values as outlined above.Storing non-plain objects (e. g.
Dates or custom classes) is not supported.Keys with
undefined` values will be considered not set.- electron-settings
Only for Electron apps, no overrides, when settings defaults, they are stored permanently in the settings file
- electron-json-storage
Only for Electron apps, focuses on storing and retrieving full JSON documents
- configstore
No support for macOS/Windows, no overrides
- conf
No overrides, only global defaults
The API of settings-store has been partially inspired by QSettings, the settings class of the Qt C++ framework.