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).)
  • Bad: y.replace(/^parent\/dirs\//, ""). Good: path.relative("/parent/dirs", y).
  • 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
• Don't use process.(get|set)(gid|uid). Windows doesn't have them. (Surround with conditionals if you must use them.) flatiron/winston#126
• 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 nodejs/node-v0.x-archive#2318 for some of the confusion. (TODO: research exactly what the best practice would be to recommend here.)

Harder to Fix

• Don't use Makefiles. 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.)

Nice!

Cool!

Another difference: socket names on windows have wierd syntax. I use the following to make sure unix paths can be translated into valid socket names:

exports.cleanPipeName = function(str) {
    if (process.platform === 'win32') {
        str = str.replace(/^\//, '');
        str = str.replace(/\//g, '-');
        return '\\\\.\\pipe\\'+str;
    } else {
        return str;
    }
};

Great stuff!

Another tip: If you're writing command-line tools (e.g. for use with "npm install --global") don't include a dot in the command name. NPM will create .bat/.cmd files as alias to your script file, but the command line won't find them if there's a dot in the name.

Don't call your command-line tool "anything.js".

Another one is to ensure that external commands, such as netsat or lsof exist across the platforms you're targetting with your packages:

https://github.com/bevacqua/dictatorship/blob/master/src/dictatorship.js

Really helpful, although my best advice for those who want to use node.js on Windows is "Don't". It's extremely unlikely that the production machine will use that operating system; you'll most likely get something Unixoid.

@JJ: Please don't assume that. I currently work on a rather large Node.js app, and our deployments are all on Windows boxes, because that's what our clients use. One of our major pain points are npm modules that frequently break on Windows, and assumptions like that only make it worse.

I recently stumbled upon this:

https://github.com/ForbesLindesay/win-spawn/blob/master/index.js

So (I know I'm coming across this very late), what would you recommend for making sure your paths turn into proper urls even if you're taking advantage of path.join and running on windows? Is the best route to simply always replace the '' with '/' when it's a url after doing a path.join?

not sure if this is newer to node but just found it in the docs and its helped me tremendously

https://nodejs.org/api/path.html#path_path_sep

Hopefully this answers your questions @kcacom

Great content! I've included some information from this and added more from personal experience with this other guide: https://github.com/ehmicky/portable-node-guide

Just to add, people add windows APIs in scripts which fails while using the same script on Node JS