Some challenges with Node.js on Windows

While there are a couple of really good Node.js IDEs (I use WebStorm), developing for Node on Windows is challenging. The platform is clearly built for Unix-type systems, and Windows support is a lagging afterthought. If your dev machine is running Windows, and you want to develop for Node, you’ll need to be aware of a number of things.

Try to use Cluster, for example, and you’ll see your code fail with no explanation. The module is marked “experimental” in the documentation, which should be a clear sign that it won’t work well if at all on Windows. If you want your code to be able to run on Windows, avoid experimental APIs.

It’s better, if you can, to test your code on a Linux machine. This can be a VM on your dev machine, or it could be a different machine. You could deploy, run, and even debug on a $35 Raspberry Pi, for example.

Another pitfall that can have you scratch your head is file encoding quirks. Line endings are different on Windows and Linux, but your Git client can take care of normalizing your files to Linux line endings when pushing your changes, and IDEs deal with those gracefully and transparently most of the time, so that’s not a big issue.

Stranger are encoding bytes. I was running the following code to parse a json file:

var settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));

The code was working fine, but then I open the JSON file in WebStorm, made a few changes, and saved it. The code started breaking with an “unexpected token” syntax error on parsing the file. The contents of the file were validating just fine in JsonLint, so it was really hard to figure out what exactly was wrong. It turned out that when I saved the file as UTF-8, it had the effect of adding encoding bytes at the beginning of the file. Those bytes are invisible in the debugger, but are enough to crash the JSON parser. This could have been fixed by re-saving the file without the encoding bytes, but that would leave a brittle application as these files need to be editable by users, so the same problem, which is hard to debug, would pop-up unexpectedly. The better solution is to make the code more resilient to such issues. It so happens that I was wrong to read and parse the file that way, because Node can use “require” on a JSON file and return the parsed object. The API handles encoding bytes. Just replacing my code with the following line fixed the issue:

var settings = require(settingsPath);

In conclusion, if you develop Node applications on Windows, you’re at a disadvantage. You might consider *gasp* getting a Mac, or running in a VM, in order to have a more standard environment for the platform. Another option that I tried and that worked surprisingly well was to build my code on Cloud9. The web-based IDE is remarkably fast, provides pretty good auto-completion and debugging features, and even lets you play with your own Ubuntu VM right in your browser. It really is astonishingly good, and I would have stayed there if I didn’t start missing some of the advanced features from WebStorm.