Tips for Writing Portable Node.js Code

portable-node.md

Tips for Writing Portable Node.js Code

(This is the kind of thing I should put on my hypothetical blog.)

I'm a Node.js user... on Windows. (Gasp!) And here are some of the issues I face every day:

Easy to Fix

In order of most-violated to least-violated:

• Don't manually construct paths. Use the path module.
  • Bad: x + "/" + y. Good: path.join(x, y). (Most likely better: path.resolve(x, y).) logicalparadox/codex@7f91b45
  • Bad: y.replace(/^parent\/dirs\//, ""). Good: path.relative("/parent/dirs", y). ryanmcgrath/wrench-js#26 (fix)
  • Be careful with module IDs versus paths; module IDs always have forward slashes. Don't conflate module IDs and filenames. substack/node-browserify#144 (fix)
  • Ditto for URLs: don't use path methods on them. LearnBoost/knox#56 (fix)
• Don't use process.(get|set)(gid|uid). Windows doesn't have them. (Surround with conditionals if you must use them.) flatiron/winston#126 (fix)
• Don't use fs.watchFile. Use fs.watch instead. logicalparadox/codex@be2fe18
• Treat module IDs/package names as case-sensitive, even though they aren't on Windows. Doing require("Q") for the q package will break for POSIX users.
• Be careful with the child_process methods. See joyent/node#2318 for some of the confusion. (TODO: research exactly what the best practice would be to recommend here.) sourcemint/sm-npm#6

Harder to Fix

• Don't depend on Makefiles for development. Windows doesn't come with make. Use package.json's scripts section instead, at the very least for test so that we Windows developers can run your tests. If you need a build solution I hear Jake and Grunt are pretty cool. You can always write a Makefile to delegate to these.
• Don't use shell scripts or other Unix-isms as part of your install process. Write them in JavaScript instead. See gist:2238951 for an example of writing a script to set up your git hooks, as well as the hooks themselves, in Node.
  • Don't call shebang'ed files, e.g. from your build scripts or with child_process, without prefixing them with node. Windows doesn't understand that.
  • Exception: git hooks (see above) seem to work, because Git for Windows understands shebangs, I guess.
• Don't barf on UTF-8 BOMs at the beginning of files. They are (very unfortunately) encouraged by Microsoft; all JavaScript files used in writing Windows 8 Metro apps must start with one, and every text file created by Visual Studio has one by default. Node itself handles them fine, so why can't you? (Projects that choke on them that have bitten me, so far: CoffeeScript and Jade.) jashkenas/coffee-script#2284

Finally

I end with two things: a thank you, and a plea.

First, thank you to @ry for making Windows a part of your Node.js efforts. I hope we Windows developers can make you proud.

Second, to everyone else: please accept pull requests! As you can see from the linked issues, many pull requests for Windows support languish, especially on the bigger projects. @substack (browserify), @indexzero (winston), and @guille (knox), I know you guys are busy, but the small-and-growing Windows community would really appreciate your support. @logicalparadox (codex) and @ryanmcgrath (wrench), thank you for working with us!