Used to access all of Atom’s configuration details.

An instance of this class is always available as the atom.config global.

Getting and setting config settings.

# Note that with no value set, ::get returns the setting's default value.
atom.config.get('my-package.myKey') # -> 'defaultValue'

atom.config.set('my-package.myKey', 'value')
atom.config.get('my-package.myKey') # -> 'value'

You may want to watch for changes. Use ::observe to catch changes to the setting.

atom.config.set('my-package.myKey', 'value')
atom.config.observe 'my-package.myKey', (newValue) ->
  # `observe` calls immediately and every time the value is changed
  console.log 'My configuration changed:', newValue

If you want a notification only when the value changes, use ::onDidChange.

atom.config.onDidChange 'my-package.myKey', ({newValue, oldValue}) ->
  console.log 'My configuration changed:', newValue, oldValue

Value Coercion

Config settings each have a type specified by way of a schema. For example we might want an integer setting that only allows integers greater than 0:

# When no value has been set, `::get` returns the setting's default value
atom.config.get('my-package.anInt') # -> 12

# The string will be coerced to the integer 123
atom.config.set('my-package.anInt', '123')
atom.config.get('my-package.anInt') # -> 123

# The string will be coerced to an integer, but it must be greater than 0, so is set to 1
atom.config.set('my-package.anInt', '-20')
atom.config.get('my-package.anInt') # -> 1

Defining settings for your package

Define a schema under a config key in your package main.

module.exports =
  # Your config schema
  config:
    someInt:
      type: 'integer'
      default: 23
      minimum: 1

  activate: (state) -> # ...
  # ...

See package docs for more info.

Config Schemas

We use json schema which allows you to define your value’s default, the type it should be, etc. A simple example:

# We want to provide an `enableThing`, and a `thingVolume`
config:
  enableThing:
    type: 'boolean'
    default: false
  thingVolume:
    type: 'integer'
    default: 5
    minimum: 1
    maximum: 11

The type keyword allows for type coercion and validation. If a thingVolume is set to a string '10', it will be coerced into an integer.

atom.config.set('my-package.thingVolume', '10')
atom.config.get('my-package.thingVolume') # -> 10

# It respects the min / max
atom.config.set('my-package.thingVolume', '400')
atom.config.get('my-package.thingVolume') # -> 11

# If it cannot be coerced, the value will not be set
atom.config.set('my-package.thingVolume', 'cats')
atom.config.get('my-package.thingVolume') # -> 11

Supported Types

The type keyword can be a string with any one of the following. You can also chain them by specifying multiple in an an array. For example

config:
  someSetting:
    type: ['boolean', 'integer']
    default: 5

# Then
atom.config.set('my-package.someSetting', 'true')
atom.config.get('my-package.someSetting') # -> true

atom.config.set('my-package.someSetting', '12')
atom.config.get('my-package.someSetting') # -> 12

string

Values must be a string.

config:
  someSetting:
    type: 'string'
    default: 'hello'

integer

Values will be coerced into integer. Supports the (optional) minimum and maximum keys.

  config:
    someSetting:
      type: 'integer'
      default: 5
      minimum: 1
      maximum: 11

number

Values will be coerced into a number, including real numbers. Supports the (optional) minimum and maximum keys.

config:
  someSetting:
    type: 'number'
    default: 5.3
    minimum: 1.5
    maximum: 11.5

boolean

Values will be coerced into a Boolean. 'true' and 'false' will be coerced into a boolean. Numbers, arrays, objects, and anything else will not be coerced.

config:
  someSetting:
    type: 'boolean'
    default: false

array

Value must be an Array. The types of the values can be specified by a subschema in the items key.

config:
  someSetting:
    type: 'array'
    default: [1, 2, 3]
    items:
      type: 'integer'
      minimum: 1.5
      maximum: 11.5

color

Values will be coerced into a Color with red, green, blue, and alpha properties that all have numeric values. red, green, blue will be in the range 0 to 255 and value will be in the range 0 to 1. Values can be any valid CSS color format such as #abc, #abcdef, white, rgb(50, 100, 150), and rgba(25, 75, 125, .75).

config:
  someSetting:
    type: 'color'
    default: 'white'

object / Grouping other types

A config setting with the type object allows grouping a set of config settings. The group will be visually separated and has its own group headline. The sub options must be listed under a properties key.

config:
  someSetting:
    type: 'object'
    properties:
      myChildIntOption:
        type: 'integer'
        minimum: 1.5
        maximum: 11.5

Other Supported Keys

enum

All types support an enum key, which lets you specify all the values the setting can take. enum may be an array of allowed values (of the specified type), or an array of objects with value and description properties, where the value is an allowed value, and the description is a descriptive string used in the settings view.

In this example, the setting must be one of the 4 integers:

config:
  someSetting:
    type: 'integer'
    default: 4
    enum: [2, 4, 6, 8]

In this example, the setting must be either ‘foo’ or ‘bar’, which are presented using the provided descriptions in the settings pane:

config:
  someSetting:
    type: 'string'
    default: 'foo'
    enum: [
      {value: 'foo', description: 'Foo mode. You want this.'}
      {value: 'bar', description: 'Bar mode. Nobody wants that!'}
    ]

If you only have a few elements, you can display your enum as a list of radio buttons in the settings view rather than a select list. To do so, specify radio: true as a sibling property to the enum array.

config:
  someSetting:
    type: 'string'
    default: 'foo'
    enum: [
      {value: 'foo', description: 'Foo mode. You want this.'}
      {value: 'bar', description: 'Bar mode. Nobody wants that!'}
    ]
    radio: true

Usage:

atom.config.set('my-package.someSetting', '2')
atom.config.get('my-package.someSetting') # -> 2

# will not set values outside of the enum values
atom.config.set('my-package.someSetting', '3')
atom.config.get('my-package.someSetting') # -> 2

# If it cannot be coerced, the value will not be set
atom.config.set('my-package.someSetting', '4')
atom.config.get('my-package.someSetting') # -> 4

title and description

The settings view will use the title and description keys to display your config setting in a readable way. By default the settings view humanizes your config key, so someSetting becomes Some Setting. In some cases, this is confusing for users, and a more descriptive title is useful.

Descriptions will be displayed below the title in the settings view.

For a group of config settings the humanized key or the title and the description are used for the group headline.

config:
  someSetting:
    title: 'Setting Magnitude'
    description: 'This will affect the blah and the other blah'
    type: 'integer'
    default: 4

Note: You should strive to be so clear in your naming of the setting that you do not need to specify a title or description!

Descriptions allow a subset of Markdown formatting. Specifically, you may use the following in configuration setting descriptions:

• bold - **bold**
• italics - *italics*
• links - [links](https://atom.io)
• code spans - `code spans`
• line breaks - line breaks<br/>
• strikethrough - ~~strikethrough~~

order

The settings view orders your settings alphabetically. You can override this ordering with the order key.

config:
  zSetting:
    type: 'integer'
    default: 4
    order: 1
  aSetting:
    type: 'integer'
    default: 4
    order: 2

Manipulating values outside your configuration schema

It is possible to manipulate(get, set, observe etc) values that do not appear in your configuration schema. For example, if the config schema of the package ‘some-package’ is

config:
someSetting:
  type: 'boolean'
  default: false

You can still do the following

let otherSetting  = atom.config.get('some-package.otherSetting')
atom.config.set('some-package.stillAnotherSetting', otherSetting * 5)

In other words, if a function asks for a key-path, that path doesn’t have to be described in the config schema for the package or any package. However, as highlighted in the best practices section, you are advised against doing the above.

Best practices

• Don’t depend on (or write to) configuration keys outside of your keypath.