How to have a config settings file in my package


I am planning to migrate my sublime plugin SyncFileYouWant into atom. Still new to atom package writing. So this question might be stupid but I have gone through the flight doc and searched quite a bit but still haven’t got an answer.

I need to have some user set config settings for this package/plugin. Something looks like this:

“mappings”: [
“source”: “/Users/lanceshi/SyncFileYouWant”,
“dest”: “/Users/lanceshi/developer/LanceTest”,
“source”: “/Users/lanceshi/SyncFileYouWant”,
“dest”: “/Users/lanceshi/developer/LanceTest2”,
“meldLocation”: “C:\Program Files (x86)\Meld\meld”

The source and dest pairs marks the source and destination location where I want to sync the files. And the number for the source/dest pairs is not limited. So I probably need to separate .json file to config this. I still haven’t found an answer to this one. Is there something like .sublime-settings file for Atom?



See the API documentation, specifically the Config Schemas section in the Config class:


Thank you for the reply. But I am still confused on how should the end user config the file after installing the package? Where should they open the config file?


Any Atom user can configure the application and any installed packages from the Settings View. The Settings View can be activated using Cmd+, on OS X or Ctrl+, on other platforms. In order to configure a package, click on the Packages tab on the left, search for the package and click Settings.


Thanks for that. I have used that to create some basic types: string, integer, boolean and they worked for me.

But I am still having issues with object and array schema. I tried array:
mappings: {
type: ‘array’,
items: {
type: ‘string’

And Object:
mapping: {
type: “object”,
properties: {
source: {
type: ‘string’
dest: {
type: ‘string’

But neither works for me. They seem to be valid JSON schema… Does Atom support array or object? What I need here is an array of objects in the settings.


The use of arrays and objects is covered in the documentation I linked above. Atom doesn’t support objects other than as a grouping mechanism inside the Settings View UI.


Thanks for that.

It seems to be an issue for atom to me though. First of all, it doesn’t support an array of objects. Second, you need to provide a default value in order to make array work. Neither of it should be the case IMO.


Part of the reason behind this restriction is that a configuration system that is too complex is just a pain for users to deal with. This is why we don’t allow complex interactions of configuration settings in the Settings View UI either. (Things like a checkbox that reveals other settings or settings influencing the values of other settings). Atom’s current system is already too complex and we would like to streamline it but haven’t figured out a design that would be better and more discoverable.

If you need something more complex, you can always store an arbitrarily complex JSON file somewhere and create the UI for it in your package.


Thank you for the clarification.


My personal experience with this matches with what @leedohm just said. What I do most of the times is:

  • keep basic configuration in the config schema so that users can easily access it
  • include a configuration file path in the schema
  • use the onDidChange on that path and the on the configuration file
  • load the configuration from the file in the localStorage in order to avoid file reads every time I need some piece of configuration file

The main downsides with this approach are that:

  • localStorage has to be refreshed every time some changes happen to the configuration file
  • a fallback mechanism should be implemented in case the configuration file is not found (your package could explode!)

Hope this helps!