Node.js usage and package authoring cheatbook. #cheatsheet

._node-cheatbook.md

I'll be collecting anything worthwhile or noteworthy I've encountered while learning to use and write Node.js packages here.

awesome-list.md

List of awesome node modules: https://github.com/sindresorhus/awesome-nodejs

discard-changes.md

git checkout-index -a -f

From: http://stackoverflow.com/a/1021384

documenting.md

There are, of course, multiple ways to document NPM/Node.js/CommonJS code. I will concern myself with in-source documentation, of which there are two types: JSDoc-like, or literate programming.

Literate Programming and Docco

Literate programming is writing code and comments in a conversational or rather literary manner, describing the process in natural language rather than tokens.

Docco is the most popular literate programming parser that I know of.

I don't write literate programming though, so that's all I have to say about that.

JSDoc-style Documentation, JSDoc3, Dox and Derivates

JSDoc, particularly the JSDoc3 version is the de-factor documentation standard for Javascript, and has a rich cross-platform following.

JSDoc itself is the most popular parser for such source, although I find it a bit of an overkill for most projects. Even though it comes from a legacy of Java code, JSDoc3 has all the necessary tags to support CommonJS and even Node style module definitions.

Dox is the other, perhaps more "celebrated" native JSDoc-style parser that only outputs JSON tags of a source and does not generate any HTML from it. It is however more powerful and elegant because of it, but also incomplete.

The trick is to find a good output generator for Dox. Doxx is one such generator that outputs html, and the other I'm using is [Markdoxx] (because getting access to raw Markdown may be more convenient and less work to display for small modules than full-blown pages.) Markdoxx, however, only supports a laughably small subset of JSDoc3 tags.

I have opted to just use JSDoc3 for building html mostly for proofreading, and jsdoc-to-markdown to generate Markdown API documentation that I can use instead of the readme, as it turns out!

es6-harmony.md

It is possible to write Node modules in ES6/Harmony. However, don't expect it to work out of the box.

As of now (stable: 0.10, unstable: 0.11) V8's ES6 support is disabled by default in Node.js However, it is possible to turn it on via options. It is worth nothing a lot of the most lucrative ES6 features are not available at all in Node 0.10, but may be in 0.11, so don't expect simply enabling harmony features on Node.js to work out of the box either.

• https://github.com/JustinDrake/node-es6-examples
  • Run Node.js as node --harmony to enable any available ES6 features.
  • Install unstable to get relative reature parity with Chrome and V8.

The other option is to transpile ES6 code into ES5 and then run it in Node. Traceur is the de-facto transpiler here, and if it does support something, it will work with the shim added (scripted on the browser, or required on Node.)

• https://github.com/google/traceur-compiler/wiki/CompilingOffline
• https://www.npmjs.org/package/traceur
  • Install as a dev dependency to compile ES6 to ES5.
• https://www.npmjs.org/package/traceur-runtime
  • Instead of pulling in all of Traceur as a runtime dependency, try this instead.
• Note: the Traceur runtime shim needs to be loaded before loading any compiled script.
  • On the browser, it's just a matter of adding the dependency as a script. Then again, already most browsers support most of spec.
  • And you will have to require('traceur') or require('traceur-runtime') before trying to import a compiled Traceur script.
    • This may be problem if you're writing a library, as you'd either have to wrap the exported module with the added requires.
    • Or manually add the require onto the compiled script.
    • And pay attention to whether you're trying to Browserify the compiled script which has no require to the runtime, as it won't be included!

Another point of note. There are modules concerned with parsin Js code that do not support ES6 yet. Uglify-js, for example, despite being enormously popular, still hasn't replied to the issue #448 describing this shortcoming. Uflify-js is used by Uglifyify for Browserify, and also in the pipeline for Lahuan.js You've been warned.

node-gyp-permission-issue.md

Many modules require node-gyp to build something native. But there's a very common problem where even NPM when ran as root will have node-gyp to fail with a permission error.

Like many of Node's relatively obscure niggling problems, this one has no "proper" fix yet. But there is a simple solution.

Simply install that module with --unsafe-perm which will cause the install scripts to be ran with root too. Needless to say, that's a terribly risky idea. But what're you going to do?

If that doesn't work, a user also has said uninstalling gyp from your distro fixes it.

node-on-the-browser.md

CommonJS requires are nifty, and definitely the best user-experience when it comes to defining and requiring Javascript modules. Unfortunately, it's designed to be synchronous and hence incompatible with the browser as it is.

There are ways around it of course, all of them come with caveats of different sizes.

1. Bundles and Browserify

The most obvious solution is bundles -- concatenating all dependencies and wrapping them with some utility code to allow their usage in the browser through requires.

And when we're talking about bundles, we're talking about [Browserify].

Which is great, it works, it's popular, and well tested. But it's a hassle to do when you're developing. Files have to be scanned and then concatenated.

And it doesn't solve out main issue of implementing moddable games, as you cann

npm-dependencies.md

By use:

• dependencies
  • Use dependencies for packages that will be required by this module in order to function.
• devDependencies
  • Use for packages only required for people who will be developing this module, such as test runners, or builders.
• peerDependencies
  • Use for dependencies which the current module expands upon.
  • Or dependencies which the module knows will be shared by a bunch of other modules,
    • especially if they belong to a collective library together.

By functionality:

• dependencies are installed on both:
  • npm install from a directory that contains package.json
  • npm install $package on any other directory
• devDependencies are:
  • also installed on npm install on a directory that contains package.json
  • not installed on npm install "$package" on any other directory, unless you give it the --dev option.
• peerDependencies, are always installed if missing, like dependencies, but unlike dependencies raise an error if multiple incompatible versions of the dependency would be used by different dependencies.

From: http://stackoverflow.com/a/22004559

npm-module-definition-patterns.md

• Export patterns: http://bites.goodeggs.com/posts/export-this/
• Creating and publishing a Node.js module: http://quickleft.com/blog/creating-and-publishing-a-node-js-module
• Location of the npm adduser generated file is ~/.npmrc

npmignore.md

It only makes sense that not all files need to be published for a Node module. For example, the test cases, or generated html docs never belong on a published module. The file .npmignore performs this function.

• https://www.npmjs.org/doc/files/package.json.html#files
• http://stackoverflow.com/a/8617868

testing.md

• tape, a lightweight TAP compliant testing framework: https://www.npmjs.org/package/tape
• Writing javascript tests with tape: http://www.catonmat.net/blog/writing-javascript-tests-with-tape/