Node.js Packaging Guidelines

To build a package that is a nodejs module, bundles or uses nodejs modules, or needs nodejs for building or testing, you need to have:

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 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 packages must use:

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

The licenses of the bundled Node.js modules need to be in the spec file. If you are using our bundling script, they will be listed in <package>-<version>-bundled-licenses.txt. It is recommended that you include <package>-<version>-bundled-licenses.txt in the rpm.

Each time you update your package, you need to verify the bundled licenses against Fedoras Software License List. Note that precompiled/minimized JavaScript may be packaged, but the requirement to verify the licenses also applies to it, see the :JavaScript guidelines.

List all unique licenses on the License: line of your spec file. Separate each license with the word "and".

If you have further questions refer to the Fedora Licensing Guidelines.

The canonical method for shipping most node modules is tarballs from the npm registry. The Source0 for such modules should be of the form https://registry.npmjs.org/<modulename>/-/<modulename>-<version>.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:

It is prefered to use tarballs for bundling node module dependencies. These tarballs should be independent from the main package source. There should be two tarballs. One for the binary, runtime package. One for testing while the package builds. This creates a smaller installed package.

These tarballs store the bundled modules in a directory called node_modules_prod, and node_modules_dev.

If your packages does not need one of the tarballs, then change these instructions accordingly. If it does not need the prod tarball, remove Source1 plus the %build and %install sections. If it does not need the dev tarball, remove Source2 and the %check section.

Note1: The setup of the prod and dev tarballs will soon become a macro. At the time of this writting, they are not.

Note2: The tarball with the dev dependencies needs to be unpacked in %check and not in %prep to avoid accidentally bundling the unpackaged dependencies that are only needed for testing.

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.

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 and bundled dependencies package.json file. Additional Requires are added to native (binary) modules to protect against ABI breaks in Node or the V8 JavaScript runtime. Additional Provides: bundled() line is added for e

For non-bundled modules only.

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.

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.

It is recommended to use the nodejs-packaging-bundler script found in the Fedora nodejs-packaging-bundler package. More documentation for it can be found at the Fedora nodejs-packaging repo .