How can we help you write packages?


+1 on docs for events - hunting around in the inspector can suffice for now, but there’s lots of trial and error.


In-house grammar documentation instead of referring to the TextMate manual, particularly with stuff where it’s unclear what Atom does or doesn’t explicitly support like recursive grammars, referencing other grammars, and so on.


I would love to see a way to write packages without being forced to write it in coffee-script. I personally dislike coffee-script and believe it hinders me for performing otherwise mundane tasks. Others love it. Both oppinions is fine, and both exists - why not allow both?


Both are allowed. There is some question around how well supported writing extensions in JavaScript are because of complications around extending the View class … but both are possible to my understanding.


I see. I did not know that. I guess some richer documentation and examples for javascript packages would be helpful. At the very lease divulge its existence. :slight_smile:


You mean like this? Re: divulging its existence

Just added a link to this answer in the FAQ.


Another thing I think could really help packages developpers is some kind of isolation mode in atom where you can run Atom with only the current package and the ones it depends upon.

The isolation should only concerns packages in the ~/.atom/packages and ~/.atom/dev/packages directories (integrated packages should always be available to avoid having an unusable editor in that mode).

In that context, packages should declares if they rely on the presence of another package(s), maybe through a package.json config.

The isolation mode could be launched with something like atom --isolate.

It will also be useful to spot which package cause some unexpected behaviors, with dozens of packages finding the culprit is quite the task. And AFAIK there’s no easy way to do that now.

What do you think ? Some issues I haven’t foreseen ?

  1. I just did a package and I constantly went through the code of Editor, EditorView and TextBuffer. There are a lot of undocumented functions that I could only learn of from there (like Editor::getBuffer which is super-useful).

  2. It would be useful if the API could have a function that returns all the viewable ranges on the screen (either fully or partially). I hacked that through my code and I consider it useful when making packages that only care about what’s visible.


+1 on the API being impossible to find. I couldn’t see a link from the Documentation page, where I would have expected. I ended up doing most of my development by reading other package’s source code and inspecting stuff in the Developer Tools :worried:


I like the promise of atom but so far I’m not finding the plugin development experience much fun.

For starters, there is no debugger, at the very least show me the exception somewhere more useful than the log. console.log is not a debugger.

A way to reload packages is needed. At the moment, for instance, I’m trying to debug a problem with the serialization so dev mode is useless.

A coffee script primer for application developers would also be nice.


Debugging is available via the Developer Tools, which can be activated via alt-cmd-I. Debugging is baked in just like in any Chromium. Go to the Sources tab, and add as many breakpoints as you want.

Reloading has been supported for a long, long time; simply press ctrl-alt-cmd-L, or click the menu item aptly named Reload (located under View).

As for documentation, what more do you need/want besides e.g. these?

There are many good tutorials and what not on CoffeeScript out there.


My debugging doesn’t work, or when it does it’s been buggy as hell and . This could be due to the windows build.

That seems to reload the entire window, which resets the log. Doesn’t help when I’m trying find out why my serialization isn’t working.

I’m also having a ton of problems using node packages. Though I’m using a windows build, so I’m not sure which are genuine problems and which are windows problems.

I’m trying to give atom the benefit of the doubt for now.


I’m willing to bet this is a Windows issue. I’ve worked on a few packages, and haven’t run into any issues with node modules. I realize this doesn’t help, but hopefully the non-OS X bugs will be resolved quickly.


Saw this thread after I posted this topic: Code-assist, auto-complete, code completion: API or guide for language packages. So I will dump the contents here too.


I found the documentation to be enough to simply set up a package in the first place, but no help in building one. The API reference has good explanations for some classes, but not for others.

I used markdown-preview as a reference for learning.

For making packages easier to write, could you have packages in development reload on save, rather than having to reload the entire editor every time I want to test something? It’s a major hindrance for the iteration cycle.


Is the major hindrance having to trigger the window:reload command to reload the editor?


I think what he means is that we have to reload the entire window each time we want to test. He wishes to only have the package one is modifying refresh alone.


So imagine I’m building something like the markdown preview pane.

Every time I hit window:reload all my tabs disappear. I have to reopen the sample markdown file I’m working on. Then I have to trigger the markdown preview.

Pretty cumbersome since a change could have just consisted of changing a css property.

The full reload takes several seconds.


It’s not impossible, but detecting when and how to deactivating/activating a package gets complicated pretty quickly and can lead to some unexpected artifacts.

But there are usually work arounds. For example, you should add a serializer to your package so you don’t have to reopen the pane (see markdown preview for an example of how to do that.)

If you are only changing the styles and Atom is run in dev mode, the changes should be automatically picked up. This is because of the dev-live-reload package. I believe this only works for .less files though.


My experience writing a package for Atom was great! The ASCII tutorial was very helpful, and I based my package on that.

Most of the info was on the documentation site, and I loved how easy it is to set up menus, keymaps, etc.

I did have to look at a couple other packages; this was because I couldn’t find any documentation on how to add package-specific settings (it would be great to include this info in the docs). Only after I looked at the Find and Replace package did I realize that the settings were stored in atom.config.

I also agree with @Jonahss about the reload time being a bit long (also the startup time). I didn’t have the disappearing tabs problem, though.

Anyhow, thanks for making developing packages so easy! I’m definitely looking forwards to writing my next one.