How can we help you write packages?


I’ve written a couple packages that add items to the status bar. You might want to look at them for ideas:


I just found atom the other week and already love it. I’ve been writing plugins to Kate and Komodo before for this and that - and it’s a nightmare in comparison.
Now, there are a bunch of packages already, but, they’re almost always buggy and lack just that feature that you need. Fortunately, these things are quickly fixed. But… Then you don’t have the git checkout of the package. And, seeing that there’s always a deadline yesterday, I don’t bother further with propagating my changes.

I propose that all packages are cloned from github as installation procedure - this way it’s super simple to fix a bug or feature and collaborate on the package.


I’m currently attempting to write a simple package that instantiates a view rendered in a new tab, and having immense difficulty. While I appreciated the ascii art tutorial, I think a more in-depth tutorial on how to write a package that actually renders output in a new tabbed view would be helpful. While it’s doable in theory to base a package off of markdown-preview (I haven’t gotten it to work yet), it’s really difficult when the API docs don’t tell you what each piece means.


I wrote the sample app html-tab as an example for this exact case. Install it like any other app…


I walked through the tutorial application and found it very useful. I’m currently digging through the API and getting familiar with some of the more advanced functionality. Some code examples in the API docs would be fantastic.


The docs could do an overview of what packages are, how Atom loads them, what ‘Generate package’ does, etc.

I initially read through the Creating your first package and Creating Packages docs. Investigating a few problems (eg. after moving my package sources around) made me realise the docs (particularly the former) really lack some basic info needed as background. Or perhaps they assume a package creator is already a seasoned Atom user (not true in my case).

Some things that would really have helped me:

  • packages are just directories in ~/.atom/packages
  • ‘generate package’ puts a symlink in there to your package source
  • which makes sense of how ‘Window reload’ works. This seemed a bit mysterious–what magic was Atom using to know where my package source files are??–until I noticed the symlinks

Perhaps this all seems terribly obvious, but they’re the kind of things that can reduce initial confusion and learning time if you’re starting from no Atom-specific knowledge at all.


I’m trying to think of a more helpful way of putting this, but in the meantime I’ll document it as a comment. Atom package development from my brief look seems extraordinarily complex and verbose. Packages to do the smallest things need vast quantities of code. To do anything substantial becomes a major project.

I think of much editor extensibility ideally being (sorry for the buzzword) agile. You see something that isn’t covered by standard facilities, and in more-or-less real-time, wire up existing editor features, often with external tools, to do what you need. Perhaps another higher-level layer of extensibity is needed? Or perhaps that’s something a package could in turn provide?

[ a bit of context: I was thinking of adding ‘go to definition’ to the go-plus package. That’s one external tool call, returning a file and line to display. To do this one small thing, there are multiple files and classes to wade through. The ROI seemed to low to be worth the time it would require]

  • There is always a trade-off between capabilities and complexity. An add-on could be very simple if a simple API was provided. But a simple API wouldn’t be nearly as hackable as Atom’ DOM and Node access.

  • Your idea of a higher-level layer of extensibity is an interesting one. It would be hard to design a good API but you should give it a try.

  • Atom packages are easy when you come from the web-dev world. Especially for full-stack developers that know the DOM and Node well. I’ve published 16 packages. Most took only one day. One took a month but it was actually an app in itself.


@mark_hahn Yes, fair points. Atom package capabilities are very ambitious, which is inevitably somewhat inimical to simplicity. And I’m not a web dev, so am not remotely fluent with javascript/DOM etc. I think a less flexible, ‘bolt-together’ form of extensibility for quick personal workflow fixes would be valuable. I’m probably not the person to do it, but I’ll keep the thought hovering about while I use Atom.


Another thing to keep in mind is that generally creating packages is about writing reusable code to work on someone else’s computer. Because of this, a certain amount of extra packaging overhead is typically considered acceptable.

On the flip side, if you wanted to just extend Atom with a little here and a little there, there are techniques for:

  • Using your styles.less in place of a Syntax or UI theme
  • Using your keymap.cson to customize Atom’s or package’s keys
  • Using your instead of writing a full package to make one little change, new command, or extension
  • etc

Essentially, you always have a “sandbox” package that you can edit on the fly. Certainly, the above techniques have a couple restrictions that a package doesn’t. But I’ve often been surprised in how much they can do. Some examples can be found at:

And sometimes my workflow consists of creating a simple command or feature in my first, using it there for days or weeks before deciding it is “production ready” and writing it up in a package to share with the community.

So looking back on my incoherent rambling here, I think Atom does have what you’re looking for but perhaps it isn’t under the general heading of “Writing a Package”.


Thanks, that’s helpful. I didn’t know about


OK, you’re right. After a couple of hours of exploration of the APIs I’ve found it’s pretty easy to add functions in without getting bogged down with the full package paraphernalia. Apart from the usefulness of that in itself, its a useful way-station towards writing packages. I’m even quite enjoying coffeescript.

Thanks for your help.


same as above, more examples and tutorials (nettuts had the best starter i have found so far). but a quicker way to reload and test a package is the most important for me, it just takes too long to quit and restart or use ctrl+alt+cmd+L, plus it loses all your windows every time…

  • All of the documentation is written solely in CoffeeScript when JavaScript examples should also coexist.
  • All of the examples seem to assume some sort of context knowledge about where to create files, what their names should be, and how to interface with them. Snippets of text with no indication as to where to create said snippet is poor practice
  • JavaScript is supposedly also supported? Which level of JS? ES5? ES6? Traceur level of JS? Equivalent to what is in Chrome? Which version? Can I use JSON wherever CSON is used? How are functions represented in this case, etc…
  • Any time a callback function is referenced, show the parameters that will be passed in and describe them. What is the context (i.e. the this object), what and how many parameters are supplied? If it is an event object, such as in the context menu actions (I think; documentation is not fantastic), what does the target object represent? Is this the best way to handle obtaining the context for the menu click? Etc…


Coffeescript is Javascript. It should only take you a few hours to learn to read CS. Longer to write it.

What files? I can’t think of any files that need to be created. Just open up a folder with your project in it.

Snippets are an add-on package. You can search for all packages in the settings tab ctrl-,.

Yes it is. Search the forum.

Javascript is a function of what chromium supports. Atom usually has latest chromium and I think the answer to all your questions is yes.

It could be better and it is steadily getting better. Pull requests are welcome. (grin)


Learning Coffeescript isn’t really the problem; I can more or less read it and I’ve already written some and posted to apm (not much mind you). The problem for me is that I just somewhat dislike it. The authors of coffeescript seem to be of the opinion that less semi-colons, brackets and parenthesis make it more readable where for me all it does is create ambiguity. I know that Coffeescript is transpiled or pre-compiled into JavaScript and when I’m not too keen on reading someone elses file, it’s easier to simply make that compilation happen and read the JavaScript.

When I said context knowledge about where to create files, what I meant by that was which file in my project do I need to create? When I create a file in my project, where should it go? Are there naming conventions? Does the name matter? These kinds of things would be significantly helpful in the documentation which sometimes explains this and usually does not.

When I spoke of snippets, it was an unfortunate choice of words given that snippets are a logical construct or thing within the editor. What I meant by that statement was that the small bits of example code indicate what one example might look like, but rarely if ever is it indicated where that bit of example code should actually live and what calls or executes it.

It could be better and it is steadily getting better. Pull requests are welcome. (grin)

I may very well do this once I understand how to make it go for myself first. Despite my frustration and apparent flailing here in the forums, I am an accomplished engineer having worked for Google, Facebook, Netflix and more. I want Atom to replace SublimeText for me being JavaScript focused rather than Python as this works better for me. I am also going to look into the 6to5 support that was mentioned in another thread as that sounds worlds better (to me) than dealing with CoffeeScript.


That is actually the biggest and most attractive thing about Atom. Both with Node and the DOM. No matter how complex and undocumented things are now the long-term potential is awesome.

One thing hurting the document situation is that the core developers have not been afraid to make major shifts in the direction before 1.0. They went from jQuery, to React, and now to HTML components. I am a firm believer that you learn by trying and changing. Atom has learned a lot.

I you can posit questions in a way that I can understand (not easy - grin) then I can help you through the mine-fields. I’ve published 17 packages including some that are even useful.


It was actually your web-browser package that I wanted to leverage. By looking through the code of other package developers I’ve found that…

      if (browser = atom.packages.getActivePackage('web-browser')) {
        console.log("[web-browser] have web-browser");

…tends to get the job done. I’m taking notes so that I can do a pull request for documentation. It would seem to me that if you are going to be interacting with another person’s package, you should first check to see if it exists before enabling code that leverages it. This should be in the documentation and I want to make sure it gets there at some point.

I am also an engineer at Facebook (although I’ll be leaving soon) and I am happy to see the choice to move to web components was made. Are there docs regarding this? Are we using the polymer-project as a polyfill? React is great but I don’t care for the black box work it does and would rather see what is happening.


The basic api docs have all been updated. You are very lucky to have joined us this close to 1.0. There have been many periods of time where the docs were totally wrong.

Ah, that is the most awesomenest part of working with atom-shell and other chromium based desktop shells. You get the latest chromium and you don’t have to worry about supporting old (and sometimes crappy) browsers. I know polymer is more complete ES6 than chromium but not as much that I’ve missed anything.

I went from web dev to Atom and when I fully realized that I didn’t have to think about whether the stuff worked everywhere I was elated. Now you try anything you want and if it works you ship it.

P.S. I know awesomenest isn’t a word but I like it so I just put it in my dictionary.


The services API is going to be the recommended way for packages to interact between each other. It is brand new though, so most package authors haven’t adopted it yet. The services API handles the checking to see that the other package is available for you.