Node.js Packaging Guidelines

To build a package containing pure JavaScript node modules, you need to have:

Additional BuildRequires are necessary for native modules. See Building native modules with node-gyp for more information.

The following macros are defined for you:

These macros are provided by the nodejs-packaging package.

During %install or when listing %files you can use the %nodejs_sitelib or %nodejs_sitearch macro to specify where the installed modules are to be found. For instance:

Using this macro instead of hardcoding the directory in the specfile ensures your spec remains compatible with the installed Node.js version even if the directory structure changes radically (for instance, if %nodejs_sitelib moves into %{_datadir}).

The canonical method for shipping most node modules is tarballs from the npm registry. The Source0 for such modules should be of the form http://registry.npmjs.org//-/-.tgz. For instance:

This method should be preferred to using checkouts from git or automatically generated tarballs from GitHub.

These tarballs store the contents of the module inside a package directory, so every package using these tarballs should use the following in %prep:

The V8 JavaScript runtime used by Node.js uses a Just-in-Time (JIT) compiler that is specially tuned to individual architectures, and must be manually ported to any new architectures that wish to support it. Node.js packages must include an ExclusiveArch line that restricts them to only these architectures.

The %{nodejs_arches} macro is provided to make this easy, so pure JavaScript modules must use:

Native (binary) modules must omit noarch and list only %{nodejs_arches} or the list of architectures as appropriate.

Most node modules do not contain their own install mechanism. Instead they rely on npm to do it for them. npm must not be used to install modules in Fedora packages, since it usually requires network access, always tries to bundle libraries, and installs files in a manner inconsistent with the Filesystem Hierarchy Standard (FHS).

Instead, install files in their proper place manually using install or cp. Most files should be installed in %{nodejs_sitelib}/ but documentation should be installed via %doc. In the event that the module ships arch independent content other than JavaScript code, that content should be installed in %{_datadir} and the module should be patched to cope with that.

The nodejs package includes an automatic Requires and Provides generator that automatically adds versioned dependencies based on the information provided in a module’s package.json file. Additional Requires are added to native (binary) modules to protect against ABI breaks in Node or the V8 JavaScript runtime.

Node.js and npm require that dependencies explicitly be included or linked into a node_modules directory inside the module directory. To make this easier, a %nodejs_symlink_deps macro is provided and will automatically create a node_modules tree with symlinks for each dependency listed in package.json. This macro should be called in the %install section of every Node.js module package.

Some node modules contain copies of other libraries in their source tree. You must remove these in %prep. Simply running rm -rf node_modules is sufficient for most modules.

%nodejs_symlink_deps outputs a warning when a node_modules directory already exists in the %buildroot, and will fail if it cannot create a symlink because a directory for it already exists.

Most native modules use the node-gyp tool to build themselves, which configures and uses the gyp build framework to build addon modules that can interact with Node.js and the V8 JavaScript interpreter used by it.

The WAF build framework has been abandoned by upstream and is not supported in Fedora.

All Node.js module spec files must include a %check section that contains (at minimum) the line:

This test ensures that the module is actually loadable, which will help avoid situations where a new upstream release has added a new dependency without the packager noticing.

Any other tests made available by upstream should also be run wherever possible.

For convienence, %nodejs_symlink_deps also accepts a --check argument, which will make it operate in the current working directory instead of the buildroot. You can use this in the %check section to make dependencies available for running tests. When this argument is used, development dependencies as listed in the "devDependencies" key in package.json are also linked.

Occasionally, there may be an update to a Node.js module that involves backwards-incompatible changes. In such situations, it may be necessary to ship a compatibility package with the older version to allow time for dependencies to migrate to the new version. The Requires generator and %nodejs_symlink_deps contain logic that handles such situations transparently for packages that depend on these modules. No special action is required for other modules that depend on multiply-versioned modules that already exist.

However, the actual multiply-versioned packages require special attention in order for this to work. To implement this, first contact the Node.js SIG mailing list, explain the situation, and include the npm module name of the affected package. The nodejs-packaging maintainers will then add it to the /usr/share/node/multiver_modules file so the package is treated specially by %nodejs_symlink_deps.

Then, in both the original package and the compatibility package, change the %install section to install the module into a versioned directory in %{nodejs_sitelib} of the form @. For instance, the 2.x uglify-js module should install into uglify-js@2.

One of the packages must additionally provide a symlink from the usual location to the versioned location described above. For instance, %{nodejs_sitelib}/uglify-js would point to %{nodejs_sitelib}/uglify-js@2 in the previous example. Typically the newest package should provide this symlink, but it might be prudent for the older version to provide it instead when introducing such a package into an existing Fedora release, so as not to break dependent packages. The symlink can then be migrated to the newest version in the next Fedora release.

Finally, any packages that depend on a version that does not provide the aforementioned symlink from the base name to the versioned directory must be rebuilt in order to work properly. To obtain a list of potentially affected packages, run reqoquery --whatrequires 'npm(module_name)' or npm view module_name dependencies. Please coordinate with the Node.js SIG if any rebuilds are necessary.