How to develop an Atom Package

So you want to build an Atom package. Some aspects of Atom make this an absolute joy, but some resources on the internet are seriously lacking, and this is my attempt to summarise all of the things I found out and learnt about building an Atom package.

Helpful Resources

  • Hacking Atom – the package development guide in Atom’s Flight Manual
  • Atom Docs – helpful for navigating your way around Atom
  • Atom’s Github – The Atom team publish all the code for Atom and Atom-published packages which can be useful for reference

Compatible Languages

  • JavaScript
  • CoffeeScript
  • Jasmine (for testing)

Generating a package

When you’ve decided whether you want to write your package in CoffeeScript or JavaScript, adjust your package generator settings.

package-generator-settings

Create in dev mode?

You can open Atom in normal or developer mode. This is useful since it means you can install packages, such as your own, on developer mode without it affecting your normal Atom mode. I recommend selecting the check box to ‘Create in Dev Mode’, however it’s not necessary.

Once you’re package has been installed running $ apm links in the command line will allow you to see which of your local packages are installed in your regular and developer atom environments.

Now we simply need to generate your Atom package template from the toolbar.

atom-package-generator

Atom will prompt you to provide the file path for where you want to store your package.

my-package-files

  • keymaps/my-package.cson – create hot-keys and shortcuts for commands in your package.
  • menus/my-package.cson – create menu options to run package commands from the Atom toolbar.
  • spec/ – store all of your test files in this folder so that the Jasmine spec runner knows what tests to run.
  • lib/ – where all of your package code will live.
  • styles/my-package.less – for any custom styling you want to add
  • package.json – how Atom will know where to retrieve the package details from (see details on publishing below).
  • LICENSE.md – update with your name as the licensee.

Testing

Now that you have your basic package set up, you can write your first test! Atom has an in-built Jasmine spec runner which you can use to run your tests.

atom-spec-runner

Writing tests for Atom packages is quite difficult. Test for simple results and play around with the Developer Tools (under the Developer menu with the spec runner) to understand it better.

Accessing Dev Mode

You can access Dev Mode via the Developer menu, however you can also open up atom from the command line in dev mode using $ atom -d or $ atom --dev.

If you haven’t generated a package yourself, for example if you are making a pull request on an existing package, you can clone the package repo to your local system and link it to your dev mode manually.

$ git clone https://github.com/atom/image-view.git
$ cd image-view
$ apm link --dev . 
$ apm unlink --dev .   (to uninstall from dev mode)
$ apm unlink --dev --all (to unlink all local packages from dev mode)

Publishing

So you’re happy with where you are with your package, and now it’s time to publish it. This is super straightforward.

  1. Push/merge to the master branch on Github: Double check as well that the master branch is the default branch on your repo.
  2. Check you have written a good README: The package generator will create a README template for you in the root directory, but you’ll need to update yours with installation and set up instructions for all of your potential users!
  3. Check your package.json file: Double check that you have updated the name, description and Github repository. Leave all other fields unchanged if you used the package generator, otherwise see Atom’s publishing guide on what to include.
  4. Get an Atom API key: Visit your Atom account page and either sign in using your Github account. Here you can generate an API token.
  5. Publish from the command line:

    $ cd your-package-name
    $ apm publish minor

    You will be prompted to enter your API key. Atom will automatically update your version number and publish the package. You’ll be able to view it at https://atom.io/packages/your-package-name.

  6. Invite people to download and code review your package: Post about it in the Atom Slack community, share it with friends and encourage them to submit issues and pull requests on your repo on Github.

Updating your package 

If you find any bugs or issues once the package has already been published, it’s easy to make changes.

  1. Push your changes to your Github repo and merge to the master branch.
  2. Depending on how big the changes you made were, you can use the same command to publish your changes.
    $ apm publish patch   (bumps the version number up by 0.0.1)
    $ apm publish minor   (bumps the version number up by 0.1.0)
    $ apm publish major   (bumps the version number up by 1.0.0)

    Again, refer to see Atom’s publishing guide on when to use each of the commands.

So there we have it, a basic guide to setting up an atom package and how to get going on developing an atom package!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s