Sunday, October 18, 2015

Hacking on Atom Part II: Building a Development Process

Over one year ago, I wrote a blog post: “Hacking on Atom Part I: CoffeeScript”. This post (Part II) is long overdue, but I kept putting it off because I continued to learn and improve the way I developed for Atom such that it was hard to reach a “stopping point” where I felt that the best practices I would write up this week wouldn't end up becoming obsolete by something we discovered next week.

Honestly, I don't feel like we're anywhere near a stopping point, but I still think it's important to share some of the things we have learned thus far. (In fact, I know we still have some exciting improvements in the pipeline for our developer process, but those are gated by the Babel 6.0 release, so I'll save those for another post once we've built them out.)

I should also clarify that when I say “we,” I am referring to the Nuclide team, of which I am the tech lead. Nuclide is a a collection of packages for Atom to provide IDE-like functionality for a variety of programming languages and technologies. The code is available on GitHub (and we accept contributions!), but it is primarily developed by my team at Facebook. At the time of this writing, Nuclide is composed of 40 Atom packages, so we have quite a bit of Atom development experience under our belts.

My Transpiler Quest

When I spun up the Nuclide project, I knew that we were going to produce a lot of JavaScript code. Transpilers such as Traceur were not very mature yet, but I strongly believed that ES6 was the future and I didn't want to start writing Nuclide in ES5 and have to port everything to ES6 later. On a high level, I was primarily concerned about leveraging the following language extensions:
  • Standardized class syntax
  • async/await
  • JSX (for React)
  • type annotations
Note that of those four things, only the first one is specified by ES6. async/await appears to be on track for ES7, though I don't know if the TC39 will ever be able to agree on a standard for type annotations or let JSX in, but we'll see.

Because of my diverse set of requirements, it was hard to find a transpiler that could provide all of these things:
  • Traceur provided class syntax and other ES6 features, but more experimental things like async/await were very buggy.
  • TypeScript provided class syntax and type annotations, but I knew that Flow was in the works at Facebook, so ultimately, that is what we would use for type annotations.
  • React came with jstransform, which supported JSX and a number of ES6 features.
  • recast provided a general JavaScript AST transformation pipeline. Most notably, the regenerator transform to provide support for yield and async/await was built on recast.
Given my constraints and the available tools, it seemed like investing in recast by adding more transforms for the other features we wanted seemed like the most promising way to go. In fact, someone had already been working on such an endeavor internally at Facebook, but the performance was so far behind that of jstransform that it was hard to justify the switch.

For awhile, I tried doing crude things with regular expressions to hack up our source so that we could use regenerator and jstransform. The fundamental problem was that transpilers do not compose  because if they both recognize language features that cause parse errors in the other, then you cannot use them together. Once we started adding early versions of Flow into the mix to get type checking (and Flow's parser recognized even less of ES6 than jstransform did), the problem became even worse. For a long time, in an individual file, we could have async/await or type checking, but not both.

To make matters worse, we also had to run a file-watcher service that would write the transpiled version of the code someplace where Atom could load it. We tried using a combination of gulp and other things, but all too often a change to a file would go unnoticed, the version on disk would not get transpiled correctly, and we would then have a subtle bug (this seemed to happen most often when interactive rebasing in Git).

It started to become questionable whether putting up with the JavaScript of the future was worth it. Fortunately, it was around this time that Babel (née 6to5) came on the scene. It did everything that we needed and more. I happily jettisoned the jstransform/regenerator hack I had cobbled together. Our team was so much happier and more productive, but there were still two looming issues:
  • Babel accepted a much greater input language than Flow.
  • It did not eliminate the need for a file-watching service to transpile on the fly for Atom.
Rather than continue to hack around the problems we were having, we engaged with the Flow and Atom teams directly. For the Flow team, supporting all of ES6 has been an ongoing issue, but we actively lobbied to prioritize to support features that were most important to us (and caused unrecoverable parse errors if they were not addressed), such as support for async/await and following symlinks through require/import statements.

To eliminate our gulp/file-watching contraption, we upstreamed a pull request to Atom to support Babel natively, just as it already had support for CoffeeScript. Because we didn't want to identify Babel files via a special extension (we wanted the files to be named .js rather than .es6 or something), and because (at least at the time), Babel was too slow to categorically transpile all files with a .js extension, we compromised on using the heuristic “if a file has a .js extension and its contents start with 'use babel', then transpile the file with Babel before evaluating it.” This has worked fairly well for us, but it also meant that everyone had to use the set of Babel options that we hardcoded in Atom. However, once Babel 6.0 comes out, we plan to work with Atom to let packages specify a .babelrc file so that every package can specify its own Babel options.

It has been a long road, but now that we are in a world where we can use Babel and Flow to develop Atom packages, we are very happy.

Node vs. Atom Packages

Atom has its own idea of a package that is very similar to an npm package, but differs in some critical ways:
  • Only one version/instance of an Atom package can be loaded globally in the system.
  • An Atom package cannot declare another Atom package as a dependency. (This somewhat follows from the first bullet point because if two Atom packages declared a dependency on different versions of the same Atom package, it is unclear what the right way to resolve it would be.)
  • Because Atom packages cannot depend on each other, it is not possible to pull in another one synchronously via require().
  • Atom packages have special folders such as styles, grammars, snippets, etc. The contents of these folders must adhere to a specific structure, and their corresponding resources are loaded when the Atom package is activated.
This architecture is particularly problematic when trying to build reusable UI components. Organizationally, it makes sense to put something like a combobox widget in its own package that can be reused by other packages. However, because it likely comes with its own stylesheet, it must be bundled as an Atom package rather than a Node package.

To work around these issues, we introduced the concept of three types of packages in Nuclide: Node/npm, Node/apm, and Atom/apm. We have a README that explains this in detail, but the key insight is that a Node/apm package is a package that is available via npm (and can be loaded via require()), but is structured like an Atom package. We achieved this by introducing a utility, nuclide-atom-npm, which loads the code from a Node package, but also installs the resources from the styles/ and grammars/ directories in the package, if present. It also adds a hidden property on global to ensure that the package is loaded only once globally.

Nuclide has many packages that correspond to UI widgets that we use in Atom: nuclide-ui-checkbox, nuclide-ui-dropdown, nuclide-ui-panel, etc. If you look at the implementation of any of these packages, you will see that they load their code using nuclide-atom-npm. Using this technique, we can reliably require the building blocks of our UI synchronously, which would not be the case if our UI components were published as Atom packages. This is especially important to us because we build our UI in Atom using React.


In July 2014, the Atom team had a big blog post that celebrated their move to React for the editor. Months later, they had a very quiet pull request that removed the use of React in Atom. Basically, the Atom team felt that to achieve the best possible performance for their editor, they needed to hand-tune that code rather than risk the overhead of an abstraction, such as React.

This was unfortunate for Nuclide because one of the design limitations of React is that it expects there to be only one instance of the library installed in the environment. When you own all of the code in a web page, it is not a big deal to commit to using only one version (if anything, it's desirable!), but when you are trying to create an extensible platform like Atom, it presents a problem. Either Atom has to choose the version of React that every third-party package must use, or every third-party package must include its own version of React.

The downside of Atom mandating the version of React is that, at some point, some package authors will want them to update it when a newer version of React comes out whereas other package authors will want them to hold back so their packages don't break. The downside of every third-party package (that wants to use React) including its own version is that multiple instances of React are not guaranteed to work together when used in the same environment. (It also increases the amount of code loaded globally at runtime.)

Further, React and Atom also conflict because they both want to control how events propagate through the system. To that end, when Atom was using React for its editor, it created a fork of React that did not interfere with Atom's event dispatch. This was based on React v0.11, which quickly became an outdated version of React.

Because we knew that Atom planned to remove their fork of React from their codebase before doing their 1.0 release, we needed to create our own fork that we could use. To that end, Jonas Gebhardt created the react-for-atom package, which is an Atom-compatible fork of React based off of React v0.13. As we did for the nuclide-atom-npm package, we added special logic that ensured that require('react-for-atom') could be called by various packages loaded by Atom, but it cached the result on the global environment so that subsequent calls to require() would return the cached result rather than load it again, making it act as a singleton.

Atom does not provide any sort of built-in UI library by default. The Atom UI itself does not use a standard library: most of the work is done via raw DOM operations. Although this gives package authors a lot of freedom, it also arrests some via a paradox of choice. On Nuclide, we have been using React very happily and successfully inside of Atom. The combination of Babel/JSX/React has facilitated producing performant and maintainable UI code.


Atom is developed as a collection of over 100 packages, each contained in its own repository. From the outside, this seems like an exhausting way to develop a large software project. Many, many commits to Atom are just minor version bumps to dependencies in package.json files across the various repos. To me, this is a lot of unnecessary noise.

Both Facebook and Google have extolled the benefits of a single, monolithic codebase. One of the key advantages over the multi-repo approach is that it makes it easier to develop and land atomic changes that span multiple parts of a project. For this and other reasons, we decided to develop the 100+ packages for Nuclide in a single repository.

Unfortunately, the Node/npm ecosystem makes developing multiple packages locally out of one repository a challenge. It has a heavy focus on semantic versioning and encourages dependencies to be fetched from Yes, it is true that you can specify local dependencies in a package.json file, but then you cannot publish your package.json file as-is.

Rather than embed local, relative paths in package.json files that get rewritten upon publishing to npm (which I think would be a reasonable approach), we created a script that walks our tree, symlinking local dependendencies under node_modules while using npm install to fetch the rest. By design, we specify the semantic version of a local dependency as 0.0.0 in a package.json file. These version numbers get rewritten when we publish packages to npm/apm.

We also reject the idea of semantic versioning. (Jeremy Ashkenas has a great note about the false promises of semantic versioning, calling it “romantic versioning.”) Most Node packages are published independently, leaving the package author to do the work of determining what the new version number should be based on the changes in the new release. Practically speaking, it is not possible to automate the decision of whether the new release merits a minor or major version bump, which basically means the process is imperfect. Even when the author gets the new version number right, it is likely that he/she sunk a lot of time into doing so.

By comparison, we never publish a new version of an individual Nuclide package: we publish new versions of all of our packages at once, and it is always a minor-minor version bump. (More accurately, we disallow cycles in our own packages' dependencies, so we publish them in topological order, all with the same version number where the code is derived from the same commit hash in our GitHub repo.) It is indeed the case that for many of our packages, there is nothing new from version N to N+1. That is, the only reason N+1 was published is because some other package in our repo needed a new version to be published. We prefer to have some superfluous package publications than to sink time into debating new version numbers and updating scores of package.json files.

Having all of the code in one place makes it easier to add processes that are applied across all packages, such as pre-transpiling Babel code before publishing it to npm or apm or running ESLint. Also, because our packages can be topologically sorted, many of the processes that we run over all of our packages can be parallelized, such as building or publishing. Although this seems to fly in the face of traditional Node development, it makes our workflow dramatically simpler.


I can't say enough good things about using async/await, which is something that we can do because we use Babel. Truth be told, as a side-project, I have been trying to put all of my thoughts around it into writing. I'm at 35 pages and counting, so we'll see where that goes.

An oversimplified explanation of the benefit is that it makes asynchronous code no harder to write than synchronous code. Many times, JavaScript developers know that designing code to be asynchronous will provide a better user experience, but give in to writing synchronous code because it's easier. With async/await, you no longer have to choose, and everyone wins as a result.


Similar to async/await, I can't say enough good things about static typing, particularly optional static typing. I gave a talk at the first mloc.js, “Keeping Your Code in Check,” demonstrating different approaches to static typing in JavaScript, and argued why it is particularly important for large codebases. Flow is a fantastic implementation of static typing in JavaScript.

Closing Thoughts

In creating Nuclide, we have written over 50,000 lines of JavaScript[1] and have created over 100 packages, 40 of which are Atom packages[2]. Our development process and modularized codebase has empowered us to move quickly. As you can tell from this essay (or from our scripts directory), building out this process has been a substantial, deliberate investment, but I think it has been well worth it. We get to use the best JavaScript technologies available to us today with minimal setup and an edit/refresh cycle of a few seconds.

Honestly, the only downside is that we seem to be ahead of Atom in terms of the number of packages it can support. We have an open issue against Atom about how to install a large number of packages more efficiently (note this is a problem when you install Nuclide via nuclide-installer, but not when you build from source). Fortunately, this should [mostly] be a simple matter of programming™: there is no fundamental design flaw in Atom that is getting in the way of a solution. We have had an outstanding working relationship with Atom thus far, finding solutions that improve things for not just Nuclide, but the entire Atom community. It has been a lot of fun to build on top of their platform. For me, working on Atom/Nuclide every day has been extremely satisfying due to the rapid speed of development and the tools we are able to provide to our fellow developers as a result of our work.

[1] To exclude tests and third-party code, I got this number by running:
git clone
cd nuclide
git ls-files pkg | grep -v VendorLib | grep -v hh_ide | grep -v spec | grep -e '\.js$' | xargs wc -l
[2] There is a script in Nuclide that we use to list our packages in topologically sorted order, so I got these numbers by running:
./scripts/dev/packages | wc -l
./scripts/dev/packages --package-type Atom | wc -l


  1. In this time of affectation, the author has composed each word with his entire being filled it.
    Life Hacks and Tips

  2. Hi I was searching for the blogs for many times, now I have reached at the right place.Procore

  3. Great and valuable information put in this blog, thank you so much for sharing this information with us. Visit OGEN Infosystem for responsive web design and SEO Service.
    SEO Service in Delhi

  4. Appslure is a reputed company based in India which provide mobile app development company in mumbai. Our website's layout will be very attractive and responsive, which will gain more visitors and you can get high lead and business from your website. Wonderful post, This article have helped greatly continue writing ..
    Mobile app development company in mumbai

  5. For assignment help, contact the
    assignment writing service for students. Original, high quality assignments from top quality writers.
    do my assignment for me

  6. Looking for a reliable online writing service provider in the U.S.A? If yes, then you are on the right platform to receive the best Assignment Help at an affordable price. We are providing remarkable academic writing services for the past many years to resolve students’ concerns. This Online Assignment Help service allows students to discuss their concerns with qualified Assignment Expert and finish their assignment on time.

  7. Wow!!! It was really an Informational Article which provide me with much Insightful Information. I would like to first thank the author for such an Insightful Content. If someone here is looking for a Website Designing Company in India, then look no further than as we are the best website designing company in Delhi working in the arena for the last 8 years.
    website designing company in India
    website designing company in NCR
    Google Partner in India

  8. Wow!!! It was a great blog with so much information of the beautiful places to visit. If anyone out there is looking for shimla manali tour package | kerala tour packages , reach out to Indian Travel Store and book your best tour package.

  9. When students help in online search they find the cost of essay writing very high. But at, we provide the best quality essays from students at low charge.
    do my essay

    do my essay online

  10. Thanks for the great article and post. Need a Industrial UPS? Don’t go beyond nexusups. “A popular Industrial UPS which offers an extensive range of exceptional Industrial UPS, and Online Online UPS Free to contact.

  11. Thanks for the great article and post. Need a servo voltage stabilizer manufacturers in india? Don’t go beyond servo star “A popular Servo Voltage Stabilizer which offers an extensive range of exceptional servo stabilizer. Feel Free to contact.

  12. Writing essays can be both time consuming and hectic. This is why most students hate the task. If nothing else is constant in your life, essay writing is what will take the place. has the best essay writing service for you. If you cannot perfect your papers or don’t know how to write a winning essay, then our service is what you need.

    uk essays help
    essay writing service
    essay typer

  13. This comment has been removed by the author.

  14. I am really impressed through reading this post and urge its writer team to share same level information. Take the association of Assignment Help team as you are in the compulsion to create assignment on committed time to your college professors.
    Assignment Help Online
    Best Assignment Help
    Assignment Helper
    Assignment Help In USA
    Online Assignment Help
    Assignment Help Experts
    Online Assignment Help Services

  15. The popularity of MA psychology course in India is increasing day by day in India and now number of students is opting for this course. Ignou University is one of the famous University for psychology. The subject code for ma psychology in Ignou is MAPC. The student need to complete the degree must clear the Ignou mapc project. Ignou synopsis offer ma psychology project to all the student who need help.

  16. Nice blog, it's so knowledgeable, informative, and a good-looking site. Myassignmenthelpau is a great platform that has been performing astonishingly well. If yes, then you are on the right platform to receive the best Assignment writing services at an affordable price. They provide transparent and trusted work satisfying universal clientele each year.

  17. Nice blog, it's so knowledgeable, informative, and a good-looking site. Myassignmenthelpau is a great platform that has been performing astonishingly well. If yes, then you are on the right platform to receive the best Buy Assignment Online at an affordable price. They provide transparent and trusted work satisfying universal clientele each year.

  18. I get all the information from your blog. Keep sharing this type of blog reguarly.If you are looking for assignment help in UK, Then you can contact us:- cs@abassignmenthelp .com

  19. Excellent information Providing by your Article, thank you for taking the time to share with us such a nice article. Amazing insight you have on this, it's nice to find a website that details so much information about different artists. Kindly visit the LiveWebTutors website we providing the best assignment help services in Australia.

    For More Info:
    My Assignment Help

  20. Thank you for this wonderful information looking forward for more. We are providing the best quality online assignment help. There are professional experts from various esteemed universities in almost every field. Well if you get time you must read more
    programming help
    online assignment help
    do my assignment
    Assignment Writing Help
    assignment help Singapore
    assignment help Canada
    assignment help Ireland
    assignment help New Zealand

  21. Assignment Help Online is the online administration where students can get full learning in any scholastic session. The points are performed by the prerequisite of students as it were.
    Accounting Assignments Online
    Digital marketing assignment writing
    Sociology assignment help

  22. I suggest all members choose My Assignment Help Australia for the best guideline in your academia. The perfect and expert assistant your requirement and learning assignment project by the university.

  23. Plumbers Near Me would give services while keeping in mind the professional norms of this industry. Customers can rely on Plumbers in my Area for all type of services that they may require.

  24. The synopsis or proposal is your opportunity to impress your teacher or supervisor and lay the preparation for a well-constructed project. Before beginning your project, you have to demonstrate you've selected a viable subject to write about. Second, your dissertation requires a skilled specialist to mark this, and thus the synopsis provides a 'snapshot' of your suggested subject and permits them to assign the right supervisor

  25. Your article is so convincing that I never stop myself from appreciating this. Thank you for posting this. If you are looking for Assignment Help online services and if you want to boost your marks without putting your efforts. If you have time issues, do contact online assignment writing service provider and receive the best assignments as per your job requirements.
    Online Assignment Help
    Assignment Help Online

  26. Get help for all makes and models of Hearing Aids. Dial us for professional and educated service for Best Hearing Aids for you and your dear ones.

  27. Get connected with the experts in an instant by dialling British Airways Phone Number and get to know about flight tickets bookings, status, schedule, booking procedure, offers, deals, services and many more. Travel the world in comfort and in luxury without paying a hefty amount. Save more by booking with us!

  28. Get your booking with American Airlines Phone Number and get the best deals. You can book your fares over a call and as per your specifications without any hassle or paperwork. Read on to know all about us and the services we offer.

  29. You will get the solution related to Air China Airlines without any hold time or waiting. The assistance available here is 24X7 and solution is guaranteed. Just enjoy a great trip and fly wherever you wish the freedom of our services. If you are looking for an authentic and quick gateway for Air China Customer Service, you can call us on our helpline number.

  30. You can arrange many more things with us. For instance, having your specific meal, having the bags checked, prior checking and carrying the first two for free and so much more. Just ask us what you need from the experts that are always at your service call us anytime at Air China Phone Number.

  31. Thank you for organizing such wonderful info. Students can now make their life easy and hassle-free by opting Assignment Help service from Assignment provider AUS. It is one stop gateway for success in the academic field. You can ask for aerospace engineering assignment help online. We will make it for you at affordable price.

  32. Hacking on Atom Part II: Building a Development Process so interesting.Nice information, valuable and excellent design, as share good stuff with good ideas and concepts.We provide best services Ecommerce Website Development Dubai for your product you visit more details.

  33. Excellent and decent post. I found this much informative, as to what I was exactly searching for. Thanks for such post and please keep on sharing with us.The Carpet Dry Cleaning Dubai provide best cleaning service you visit more info.

  34. Excellent Post, Positive site, your article is so helpful for readers, who are feeling stress for his assignment. You can contact UK Assignment Helpservices. Here is a team of expert writers ready to giving you their services at a low cost.

  35. Reserve your tickets and get ready to witness the beauty of these places. You can easily avail deals and discounts on Los Angeles To Seattle Flights.

  36. Great I found informative content Keep up the good work and keep sharing awesome information like this.
    Nursing Assignment Help Online
    Macroeconomics Homework Help

  37. Some people also feel the urge of staying close to their parents to take care for them. content writing services

  38. I love it when people get together and share views. Great site, Eunidrip company has wealth of experience in drilling boreholes. Our aim is to provide quality, clean water and boreholes that can be well maintained and long lasting. We are a Class “A” water contractor certified by the Ministry of water and Irrigation. Greenhouse Construction in Kenya for more.

  39. The word building is both a noun and a verb: the structure itself and the act of making it. As a noun, a building is 'a structure that has a roof and walls and stands more or less permanently in one place. Mobile App Development Dubai are the best in town providing best quality apps, which users require.

  40. Myassignmenthelp offers customized and unique assignment help through actual professionals. Our team of PhD. certified experts strive to meet students’ expectations along with University guidelines to ensure high scoring assignments every time. Along with adept writing help we offer professional proofreading, editing, free samples and exam help to assist students in achieving their career aspirations.

  41. ABC Assignment help is the finest assignment help company offering reliable assistance to students across the globe. Our team of subject-specific writers are available 24x7 with their expertise, experience and dedication to provide professional academic writing service for assignments, essays, coursework and more.

    Read More - Rhino Assignment Help

  42. Thank you for bringing to a halt my long search topic. I really benefited from your content. If you are experiencing trouble striking a balance between your busy academic life and handling your online classes, you can get help from a professional who will take online classes on your behalf. It doesn’t matter the kind of help you need, whether it is passing your exam, finishing your assignments or even the entire classwork, you can get help here at Online Class Help .

  43. The shortcut to demonstrating a strong passionate about analytics is to cultivate some genuine interest in data. If you're serious about a job with data, go the whole hog and evolve into a numbers person.

  44. csv to vcard online is a free contacts file converter, it can convert contacts files in CSV format to vCard files. The usage is simple, click the button "Browse" to select a contacts file

  45. Very nicely explained and include all important information.I also recommend visiting mobile app development company

  46. How To export exchange 2003 mailbox to pst files. Run the exmerge.exe and select the option for a two step procedure and select the users to export the mailboxes. You are done!

  47. Siddharth Shukla is an Indian television actor. He is primarily known for his work in a small screen and Bollywood industry.

  48. Get the best expert advice for physics assignment help online. our assignment is plagiarism-free, reliable and mistake-proof. we ensure you quality assignment help service.
    Visit our website: Physics Assignment Help

  49. If you want to know about the Best Time to Book Flights, reach to our customer care and clear all your worries. Get ready to buy airline tickets with us!

  50. is the world's best online assignment services provider They do not make empty promises, always achieved what they promised. So you can take help with any academic consultation or Assignment Help . Our team of online get assignment help online is always ready to cater to your needs at any given moment.

  51. If you are eager to travel with Spirit Airlines Book A Flight, then contact our Experts. Our experts are available 24/7 at your service.

  52. If you are facing problems with your televsion, Best Buy TV Repair team can help you 24/7. We provide assistance for all the models. Contact 24/7.

  53. In these difficult Coronavirus situations, Qatar Airways Flights is offering flight change flexibility with its option. Read more to know about flight flexibility.

  54. The operation of Qatar Airways Flights is still going in Coronavirus situations. However, Qatar Airways is offering flight change flexibility. Read Now!!

  55. I think this is one of the best blog for me because this is really helpful for me. Thanks for sharing this valuable information for free...
    packers and movers in dhanbad

  56. Flight reservation is never easier than before! Experience Book a Flight With Southwest Airlines experience with us. From deals to 24/7 help we got you covered!

  57. Air Canada Airlines Flights is the choice of millions but are you aware of everything related to Book A Flight With Air Canada Airlines. Find out!