Writing an io.js-compatible npm module

Question

Should I reference io.js in my package.json? And is there anything else I should do differently if I want to write a module that is compatible with both Node and io.js?

Answer 1

Heroku documentation says that you can add "iojs" entry to "engines" section of package.json.

Answer 2

First of all, you should consult the io.js changelog that describes the changes made to io.js since release 1.0.0, which, as they say, introduced major changes to the API (compared to Node.js 0.11.14, which was the development version at the time of the fork).

Since following semver means that a major version bump introduces backwards-incompatible changes, this means that you will have to handle these differences in your application and utilise proper API calls depending on the platform.

A quick read through the changelog seems to indicate that the differences among existing APIs are not that significant, but there are areas where you will have to take extra care. There are quite a lot of new APIs in io.js that are not natively available on Node.js so you will probably be unable to use them (or provide some compatibility layer that adds these to Node.js, if possible).

Additionally, since ECMAScript 6 features are implemented at different levels among Node.js 0.10, 0.12 and io.js, you must choose which ones of these features you can use in order to remain compatible, depending on which platforms and version you need/choose to support.

Warning - personal opinion follows

This question is the exact reason why I do not approve of the team behind io.js forking it and introducing backwards-incompatible changes and still using the Node.js package manager, npm, to handle dependencies for their new platform. You either end up writing packages for only one of them or you use some crazy decision logic to choose how to call a function, because that function's signature differs between the two.

In the end, the developers get frustrated and leave for another project/language, the community and module availability gets fragmented and no one ever wins.

I sincerely hope that instead of splitting, the community will choose one platform and the other will simply die out, no matter which of the two (Node.js or io.js) that would be. Or, that the projects converge at some point, integrating the best of both into one platform.