This document is still work in progress.

Please check the mailing list archives for the latest discussions about it.

Node.js modules policy

This page describes the policy that packages with Node.js modules should follow.

Policy in brief

  1. the binary and the source package should be called node-foo

  2. must build depends on nodejs

  3. should be installed to /usr/lib/nodejs/ or /usr/lib/nodejs/foo/, depends whether the module is contained in a single file or in multiple files

  4. should have package.json shipped in /usr/lib/nodejs/foo/package.json

  5. should generate a libjs-foo binary package if the script is usable also for web-broser (see Javascript/Policy for more info)

Policy in details


A module typically has already a source tree layout with directories like "lib", "bin", and a package.json file at its root.

Installing is as simple as:

This usually allows source to be kept unpatched (except for the nodejs rename):

Please refer to the upstream documentation (also available in /usr/share/doc/nodejs/api/modules.html#modules_folders_as_modules) to understand how to correctly Node.js looks up for modules.

Excluding auto-generated files from source

Strict application of DFSG requires files generated from source in upstream tarball to be excluded, unless it is possible to regenerate the files and prove they are identical to the ones in the tarball.

Minified files and browserified files are examples of such files that could be excluded for that reason. A convenient way to achieve this is to use the Files-Excluded field in debian/copyright, for more information please see UscanEnhancements.

Declare a build-dependency on nodejs

The nodejs package depends on libv8 and doesn't build on some architectures. Because of that, node-* packages having "Architecture: all" are available on architectures where nodejs isn't available - and so are uninstallable on those architectures. To work around that inconvenience to the users, simply declare an unversioned "Build-Depends: nodejs".

Declaring that build-dependency is also quite natural in the case of a package running its test suite during its build.

Patching binaries shebang

While the entire world use node as command name for Node.js framework, in Debian the correct name is nodejs, because it conflicts with another package called node as well.

Technical committee decided to fix this by renaming node to nodejs.

To comply to this, it is often as simple as:

Some programs are a bit less obvious to fix, for example they can spawn nodejs instances using "node" name.