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.
- 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
- Jasmine (for testing)
Generating a package
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 will prompt you to provide the file path for where you want to store your package.
- 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.
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.
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)
So you're happy with where you are with your package, and now it's time to publish it. This is super straightforward.
- Push/merge to the master branch on Github: Double check as well that the master branch is the default branch on your repo.
- 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!
- 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.
- 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.
- Publish from the command line:
$ cd your-package-name $ apm publish minorYou 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.
- 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.
- Push your changes to your Github repo and merge to the master branch.
- 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!