Configuring Atom

I've been using Atom for a while now, and I thought I'd write a blog post describing some quick ways to modify Atom to work better for you. GitHub describes Atom as "modern, approachable, yet hackable to the core". This post will focus mostly on the "approachable" side of customizing your editor. We'll first look at editor and package settings before moving to configuration files you can modify, with a few small examples of how you can use them.

NOTE: As of writing, Atom is on version 1.7.4, and the beta build is 1.8.0-beta4.

Settings

Editor Settings

This is a good place to look when starting to use Atom. There aren't too many settings here, and the options available to you can be very useful. One of the more common options you might look at here is the font-family that will be applied to your editor's text. Another option that is important to know about is Exclude VCS Ignored Paths. With this option enabled, files ignored from version control will not show up when using the fuzzy-finder and find-and-replace packages. This can help eliminate search results that may be irrelevant while also improving performance. For an example of how this can help, try toggling the setting and using fuzzy-finder and find-and-replace on a project with a large node_modules folder. Enabling this behavior may be detrimental to your workflow if you routinely edit files you have ignored by your VCS, so knowing about this option can help avoid some frustration.

Package Settings

The majority of the modifications you can make to Atom will come from packages. There are a ton of community made packages to browse through, but a fresh install of Atom will still contain many core packages that you'll find useful. Navigate to your Preferences and select "Packages" from the menu on the left. You can search through your installed packages here. There will be a settings button next to the package name if that package has settings you are able to configure.

I'd recommend browsing through your package list for the things you use most often. If you use autocomplete a lot, check out the settings for autocomplete-plus. Language support is also contained in packages. The language support packages that ship with Atom usually follow the naming convention of language-<name>. Be sure to check out the packages for the languages you work with to see settings for things like maximum line length and indentation preferences. These settings allow you to keep style preferences in line with your team's style guide. Language packages may also include available keybindings, and snippets used in conjunction with autocomplete.

Configuration Files

Init Script

You can open your init script by opening the command palette with cmd-shift-p and searching for the command Application: Open Your Init Script. This CoffeeScript or JavaScript file will be evaluated after all of your packages are loaded. This is a good place to write some code to hack together custom commands and modifications that aren't limited to a single package you have installed, and aren't suited to be its own package. This file is also great for prototyping new package ideas or modifications you are thinking of developing.

Recently I've been learning React, and found myself frequently changing the grammar for a file from regular JavaScript to JavaScript (JSX) for better syntax highlighting and autocomplete behavior. This was a perfect use case for the init script. I changed this process from 3 commands to 1 by creating a custom command in my init script. The code for this is below if you'd like to try it out yourself, but I won't dive into the Atom API in this post. Check the documentation for more details.

atom.commands.add 'atom-text-editor', 'custom:js-to-jsx', ->
  grammars = atom.grammars.getGrammars()
  grammar = grammars.find((g) ->
    g.name == "JavaScript (JSX)"
  )
  editor = atom.workspace.getActiveTextEditor()
  editor.setGrammar(grammar)

Keymap

Are you sick of accidentally quitting Atom instead of closing a tab? Let's override the cmd-q keybinding! We can do this by editing our keymap file. Open your keymap the same way you opened your init script, but this time looking for the Application: Open Your Keymap command. This is a CSON or JSON file that you can use to map a keybinding to a command. Your first step when creating a new keybinding is finding the selector you want to apply the keybinding to. For example, you can use atom-text-editor to refer to your text editing area, or body for just about everything in the application window. Atom includes Chrome's developer tools (View -> Developer -> Toggle Developer Tools), which can help you find the right selector. The next option is the keybinding you wish to apply. We want to override cmd-q to save, and make sure we can still quit Atom with a second press. In this case we will have two keybindings: cmd-q and cmd-q cmd-q. The last step is the name of the command we want to dispatch. Command names are usually in the format package-name:command-name. The quit command, like the commands used to open the keymap and init files, is part of Application and is called application:quit. Saving is part of Atom Core, and is attached to the command core:save. Putting all this together, we would get the following:

'body':
  'cmd-q': 'core:save'
  'cmd-q cmd-q': 'application:quit'

This overrides cmd-q to save, and allows you to confirm quitting with another cmd-q.

Stylesheet

Your stylesheet, styles.less, is used to customize how your editor looks. You can open this file by running the "Application: Open Your Stylesheet" command. You can use this to apply styles to the core editor, as well as views created by third party packages. You can even modify styles set by your syntax theme to get it just right.

I use panes often, and sometimes lose track of which pane I'm focused on. I was able to solve this small but annoying problem by adding a blue border around my active pane.

atom-pane {
  border: 1px solid #000000;
  &.active {
    border: 1px solid #3fcef4;
  }
}

Snippets

Snippets are your way of adding custom autocomplete options. You can edit your snippets by running the 'Application: Open Your Snippets' command. Snippets are defined using CSON or JSON. The outer most key is the language scope. You can find this by looking at the package settings for a language. For language-ruby this is source.ruby, and for language-javascript it's source.js. Each key within this source is the short description of what this snippet is for. There are two attributes that you should add inside of that description. The first is a prefix, used as the "trigger" for autocomplete. The next is the body, which will be the text inserted when the snippet is confirmed. An example I use to set up a describe method when testing ruby is below.

'.source.ruby':
  'describe block':
    'prefix': 'describe'
    'body': """
      describe '${1:message}' do
        $2
      end
    """

The dollar signs are Tab Stops, used to signal which part of the snippets are supposed to be edited after the snippet is confirmed.

Summary

This is a very high level overview of where different settings can be found and modified. The Atom team has written much more detailed documentation for these settings and more. The main documentation can be found here. It includes entire sections on Packages, Snippets, The Init File, and Keymaps if you would like to learn more about the specific topics covered in this blog post.


by Alex Egan