Options
All
  • Public
  • Public/Protected
  • All
Menu

Index

Type aliases

Config

Config: { atomicSave: boolean; dir?: undefined | string; electron?: typeof Electron; fileName: string; numSpaces: number; prettify: boolean }

Config types contain all the configuration options for Electron Settings that can be set using configure().

Type declaration

  • atomicSave: boolean

    Whether or not to save the settings file atomically.

  • Optional dir?: undefined | string

    The path to the settings directory. Defaults to your app's user data direcory.

  • Optional electron?: typeof Electron

    A custom Electron instance to use. Great for testing!

  • fileName: string

    The name of the settings file that will be saved to the disk.

  • numSpaces: number

    The number of spaces to use when stringifying the data before saving to disk if prettify is set to true.

  • prettify: boolean

    Whether or not to prettify the data when it's saved to disk.

KeyPath

KeyPath: string | Array<string | number>

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.

SettingsObject

SettingsObject: {}

A SettingsObject is an object whose property values are of the type SettingsValue.

Type declaration

SettingsValue

SettingsValue: null | boolean | string | number | SettingsObject | 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);

Core Functions

get

  • Gets all settings. For sync, use getSync().

    example

    Gets all settings.

    const obj = await get();

    Returns Promise<SettingsObject>

    A promise which resolves with all settings.

  • Gets the value at the given key path. For sync, use getSync().

    category

    Core

    example

    Get the value at color.name.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    const value = await settings.get('color.name');
    // => "cerulean"
    example

    Get the value at color.hue.

    const h = 'hue';
    const value = await settings.get(['color', h]);
    // => undefined
    example

    Get the value at color.code.rgb[1].

    const h = 'hue';
    const value = await settings.get('color.code.rgb[1]');
    // => 179

    Parameters

    • keyPath: KeyPath

      The key path of the property.

    Returns Promise<SettingsValue>

    A promise which resolves with the value at the given key path.

getSync

  • Gets all settings. For async, use get().

    example

    Gets all settings.

    const obj = getSync();

    Returns SettingsObject

    All settings.

  • Gets the value at the given key path. For async, use get().

    category

    Core

    example

    Get the value at color.name.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    const value = settings.getSync('color.name');
    // => "cerulean"
    example

    Get the value at color.hue.

    const h = 'hue';
    const value = settings.getSync(['color', h]);
    // => undefined
    example

    Get the value at color.code.rgb[1].

    const h = 'hue';
    const value = settings.getSync('color.code.rgb[1]');
    // => 179

    Parameters

    • keyPath: KeyPath

      The key path of the property.

    Returns SettingsValue

    The value at the given key path.

has

  • has(keyPath: KeyPath): Promise<boolean>
  • Checks if the given key path exists. For sync, use hasSync().

    example

    Check if the value at color.name exists.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    const exists = await settings.has('color.name');
    // => true
    example

    Check if the value at color.hue exists.

    const h = 'hue';
    const exists = await settings.has(['color', h]);
    // => false
    example

    Check if the value at color.code.rgb[1] exists.

    const exists = await settings.has(color.code.rgb[1]);
    // => true

    Parameters

    • keyPath: KeyPath

      The key path to check.

    Returns Promise<boolean>

    A promise which resolves to true if the keyPath exists, else false.

hasSync

  • hasSync(keyPath: KeyPath): boolean
  • Checks if the given key path exists. For async, use hasSync().

    example

    Check if the value at color.name exists.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    const exists = settings.hasSync('color.name');
    // => true
    example

    Check if the value at color.hue exists.

    const h = 'hue';
    const exists = settings.hasSync(['color', h]);
    // => false
    example

    Check if the value at color.code.rgb[1] exists.

    const exists = settings.hasSync(color.code.rgb[1]);
    // => true

    Parameters

    • keyPath: KeyPath

      The key path to check.

    Returns boolean

    true if the keyPath exists, else false.

set

  • Sets all settings. For sync, use setSync().

    example

    Set all settings.

    await settings.set({ aqpw: 'nice' });

    Parameters

    Returns Promise<void>

    A promise which resolves when the settings have been set.

  • Sets the value at the given key path. For sync, use setSync().

    category

    Core

    example

    Change the value at color.name to sapphire.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    await settings.set('color.name', 'sapphire');
    example

    Set the value of color.hue to blue-ish.

    const h = 'hue';
    await settings.set(['color', h], 'blue-ish);
    example

    Change the value of color.code.

    await settings.set('color.code', {
      rgb: [16, 31, 134],
      hex: '#101F86'
    });

    Parameters

    Returns Promise<void>

    A promise which resolves when the setting has been set.

setSync

  • Sets all settings. For async, use set().

    example

    Set all settings.

    settings.setSync({ aqpw: 'nice' });

    Parameters

    Returns void

  • Sets the value at the given key path. For async, use set().

    category

    Core

    example

    Change the value at color.name to sapphire.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    settings.setSync('color.name', 'sapphire');
    example

    Set the value of color.hue to blue-ish.

    const h = 'hue';
    settings.setSync(['color', h], 'blue-ish);
    example

    Change the value of color.code.

    settings.setSync('color.code', {
      rgb: [16, 31, 134],
      hex: '#101F86'
    });

    Parameters

    Returns void

unset

  • unset(): Promise<void>
  • unset(keyPath: KeyPath): Promise<void>
  • Unsets all settings. For sync, use unsetSync().

    example

    Unsets all settings.

    await settings.unset();

    Returns Promise<void>

    A promise which resolves when the settings have been unset.

  • Unsets the property at the given key path. For sync, use unsetSync().

    category

    Core

    example

    Unset the property color.name.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    await settings.unset('color.name');
    
    await settings.get('color.name');
    // => undefined
    example

    Unset the property color.code.rgba[1].

    await settings.unset('color.code.rgba[1]');
    
    await settings.get('color.code.rgb');
    // => [0, null, 230]

    Parameters

    • keyPath: KeyPath

      The key path of the property.

    Returns Promise<void>

    A promise which resolves when the setting has been unset.

unsetSync

  • unsetSync(): void
  • unsetSync(keyPath: KeyPath): void
  • Unsets all settings. For async, use unset().

    example

    Unsets all settings.

    settings.unsetSync();

    Returns void

  • Unsets the property at the given key path. For async, use unset().

    category

    Core

    example

    Unset the property color.name.

    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }
    
    settings.unsetSync('color.name');
    
    settings.getSync('color.name');
    // => undefined
    example

    Unset the property color.code.rgba[1].

    settings.unsetSync('color.code.rgba[1]');
    
    settings.getSync('color.code.rgb');
    // => [0, null, 230]

    Parameters

    • keyPath: KeyPath

      The key path of the property.

    Returns void

Other Functions

configure

  • configure(customConfig: Partial<Config>): void
  • Sets the configuration for Electron Settings. To reset to defaults, use reset().

    Defaults:

    {
      atomicSave: true,
      fileName: 'settings.json',
      numSpaces: 2,
      prettify: false
    }
    example

    Update the filename to cool-settings.json and prettify the output.

    settings.configure({
      fileName: 'cool-settings.json',
      prettify: true
    });

    Parameters

    • customConfig: Partial<Config>

      The custom configuration to use.

    Returns void

file

  • file(): string
  • 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.

    • macOS - ~/Library/Application\ Support/<Your App>
    • Windows - %APPDATA%/<Your App>
    • Linux - Either $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().

    example

    Get the path to the settings file.

    settings.file();
    // => /home/nathan/.config/MyApp/settings.json

    Returns string

    The path to the settings file.

reset

  • reset(): void
  • Resets the Electron Settings configuration to defaults.

    example

    Reset configuration to defaults.

    settings.reset();

    Returns void

Legend

Generated using TypeDoc