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 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 Creating a Package 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

object

Value must be an object. This allows you to nest config options. Sub options must be under a properties key

config:
  someSetting:
    type: 'object'
    properties:
      myChildIntOption:
        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'

Other Supported Keys

enum

All types support an enum key. The enum key lets you specify all values that the config setting can possibly be. enum must be an array of values of your specified type. Schema:

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

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.

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!

Best practices

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