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 user settings to the disk so that they can be loaded in the next time your app starts.

Also, you can [observe key paths][method_observe] and get notified if their value changes. So that's pretty neat.

Note: v2 is not compatible with earlier versions of electron-settings.

---

Install

$ npm install electron-settings

Quick Start

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

settings.set('name', {
  first: 'Cosmo',
  last: 'Kramer'
}).then(() => {
  settings.get('name.first').then(val => {
    // => "Cosmo"
  });
});

settings.getSettingsFilePath();
// => /Users/You/Library/Application Support/YourApp/Settings

Default Settings

You can configure default settings by using settings.defaults(). This will set the defaults object globally. If this is the first time the settings file is being accessed, the defaults will be applied automatically.

settings.defaults({
  foo: 'bar'
});

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

Additionally, you can use applyDefaults() or resetToDefaults() to fit your needs.

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 object dot notation in string form.

  For example, in the JSON object below the value at the key path "foo.bar" is "baz".

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

• Where is the settings file saved?

  The settings file is named Settings and is saved in your app's user data directory:

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

  You can use getSettingsFilePath() to get the full path to the settings file.

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

  Yes! Just be aware that if the window closes during an async operation, data may be lost.

• 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.

• Why do I have to use promises?

  electron-settings reads and writes to the file system asynchronously. In order to ensure data integrity, you should use promises. Alternatively, all methods have a synchronous counterpart that you may use instead.

---

Documentation

• Events
• Methods

Contributors

• Nathan Buchar (Owner)
• Kai Eichinger
• You?

License

ISC

---

Last updated Aug. 2nd, 2016 by Nathan Buchar.

Having trouble? Get help on Gitter.