electron-settings

electron-settings

A simple persistent user settings manager for Electron.

Originally adapted from Atom's own configuration manager, electron-settings allows you to save your users' settings to the disk so that they can be loaded in the next time your app starts without skipping a beat.

Also, you can subscribe to settings and get notified when their value changes. So that's pretty neat.

---

Install

$ npm install --save electron-settings

Demo

const settings = require('electron-settings');

settings.set('name', {
  first: 'Cosmo',
  last: 'Kramer'
});

settings.get('name.first');
// => "Cosmo"

settings.has('name.middle');
// => false

FAQ

• What is a "key path"?

  With electron-settings, you are not just setting keys like you would with local storage. Instead, you are working with a JSON object, and a key path is a string that points to a specific key within that object—essentially using object dot notation in string form.

  For example, in the JSON object below the value at the key path "foo" is the object { bar: 'baz' }, and the value at the key path "foo.bar" is the string "baz".

  {
    "foo": {
      "bar": "baz"
    }
  }
  

• What data types may be stored?

  You may set a key path to any value supported by JSON: an object, array, string, number, boolean, or null.

  Unfortunately, dates and other special object types will be type converted and lost, because JSON does not support anything other than the aforementioned data types.

• Where is the settings file saved?

  Settings are saved in your app's user data directory in a file called Settings.

  • ~/Library/Application Support/YourApp on MacOS.
  • %APPDATA%/YourApp on Windows.
  • $XDG_CONFIG_HOME/YourApp or ~/.config/YourApp on Linux.

• Can I use electron-settings in both the main and renderer processes?

  You bet!

---

Methods

• has()
• get()
• getAll()
• set()
• setAll()
• delete()
• deleteAll()
• watch()

---

• has()

  settings.has(keyPath):boolean

  Returns a boolean indicating whether the settings object contains the given key path.

  ---

  Parameters

  • keyPath String

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Checks if the settings contains the key path "foo.bar".

  settings.has('foo.bar');
  // => true
  

  Checks if the settings contains the key path "qux".

  settings.has('qux');
  // => false
  

• get()

  settings.get(keyPath[, defaultValue]):any

  Returns the value at the given key path, or sets the value at that key path to the default value, if provided, if the key does not exist. See also: getAll().

  ---

  Parameters

  • keyPath String
  • defaultValue Any - The value to apply if the setting does not already exist.

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Gets the value at "foo".

  settings.get('foo');
  // => { "bar": "baz" }
  

  Gets the value at "foo.bar".

  settings.get('foo.bar');
  // => "baz"
  

  Gets the value at "qux".

  settings.get('qux');
  // => undefined
  

  Gets the value at "qux", with a default fallback.

  settings.get('qux', 'aqpw');
  // => "aqpw"
  

• getAll()

  settings.getAll():Object

  Returns all settings. See also: get().

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Gets all settings.

  settings.getAll();
  // => { "foo": { "bar": "baz" } }
  

• set()

  settings.set(keyPath, value[, options])

  Sets the value at the given key path. See also: setAll().

  ---

  Parameters

  • keyPath String - The path to the key whose value we wish to set. This key need not already exist.
  • value Any - The value to set the key at the chosen key path to. This must be a data type supported by JSON: an object, array, string, number, boolean, or null.
  • options Object (optional)
    • prettify Boolean (optional) - Prettify the JSON output. Defaults to false.

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Changing the value at the key path "foo.bar" from "baz" to "qux".

  settings.set('foo.bar', 'qux');
  
  settings.get('foo.bar');
  // => "qux"
  

  Setting the value at the key path "new.key".

  settings.set('new', 'hotness');
  
  settings.get('new');
  // => "hotness"
  

• setAll()

  settings.setAll(obj[, options])

  Sets all settings. See also: set().

  ---

  Parameters

  • obj Object - The new settings object.
  • options Object (optional)
    • prettify Boolean (optional) - Prettify the JSON output. Defaults to false.

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Sets all settings.

  settings.setAll({ new: 'hotness' });
  
  settings.getAll();
  // => { "new": "hotness" }
  

• delete()

  settings.delete(keyPath[, options])

  Deletes the key and value at the given key path. See also: deleteAll().

  ---

  Parameters

  • keyPath String
  • options Object (optional)
    • prettify Boolean (optional) - Prettify the JSON output. Defaults to false.

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Deleting "foo.bar".

  settings.delete('foo.bar');
  
  settings.get('foo');
  // => {}
  

• deleteAll()

  settings.deleteAll([options])

  Deletes all settings. See also: delete().

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Deletes all settings.

  settings.deleteAll();
  
  settings.getAll();
  // => {}
  

• watch()

  settings.watch(keyPath, handler):Function

  Watches the given key path for changes and calls the given handler if the value changes. To unsubscribe from changes, call dispose() on the Observer instance that is returned.

  ---

  Parameters

  • keyPath String - The path to the key that we wish to watch for changes.
  • handler Function - The callback that will be invoked if the value at the chosen key path changes. Passes the following as arguments:
    • newValue Any
    • oldValue Any

  ---

  Examples

  Given:

  {
    "foo": {
      "bar": "baz"
    }
  }
  

  Watch "foo.bar".

  settings.watch('foo', (newValue, oldValue) => {
    console.log(newValue);
    // => "qux"
  });
  
  settings.set('foo.bar', 'qux');
  

  Dispose the key path watcher after the value has changed once.

  const observer = settings.watch('foo', newValue => {
    observer.dispose();
  });
  
  settings.set('foo', 'qux');
  });
  

Authors

• Nathan Buchar (Owner)

License

ISC

---

Having trouble? Get help on Gitter.