Some node modules are rather small and sometime are dependency of only one package. To avoid having many node modules, and uscan provides hooks that can be used to simplify maintenance.

This chapter is a guidelines, no a set of rules. If you have any doubt, write a mail to Debian JS Team mailing list.

Some acceptable reasons to embed a node module:

If you have any doubt, write a mail to Debian JS Team mailing list

Adding component version in package version allows uscan to follow upstream changes? This is a security point and must be examined using this point of view. Guidelines to add component version in package version:

Do I have to export embedded modules or not?

As explained after, you can export components or not using Provides: field in debian/control. Some guidelines to choose:

Building a multiple npmjs source package

In this example, we are building node-test package (named test in including ta and tb npmjs modules.

Step 0: verify that embedded modules don't exist already

To avoid package conflicts and embedded copies:

If component doesn't exist there, insert its (Debian) name in pending embedded modules. Please clean also this list when package has been accepted in unstable.

Step 1: debian/gbp.conf and debian/watch

git-buildpackage will build embedded sources automatically if both debian/gbp.conf and debian/watch are well configured:

component = [ 'ta', 'tb' ]

opts="searchmode=plain,pgpmode=none" \ \\d[\d\.]*)@ARCHIVE_EXT@ group

opts="searchmode=plain,pgpmode=none,component=ta" \ \\d[\d\.]*)@ARCHIVE_EXT@ group

opts="searchmode=plain,pgpmode=none,component=tb" \ \\d[\d\.]*)@ARCHIVE_EXT@ group

See uscan manpage for more. Quick explanations:

Step 2: download sources

Launch uscan, then gbp import-orig --pristine-tar ../<main>.orig.tar.xz will upload all components even if they are new. The source directory contains now upstream source and one directory per sub module named by their component name:

$ ls -l

Then update debian/changelog version. Example:

dch -v 3.1.4+~3.0.2+~3.1.3-1 'Import upstream version 3.1.4+~3.0.2+~3.1.3-1'

Step 3: configure debian/* files


To avoid multiple embedding, you must share sub components with other. This is done by adding a "Provides:" field in debian/control: Note what for smooth upgrade improvement main package is called node-debbundle-foo (allow simpler merge/split if needed)

Package: node-debbundle-foo
Depends: ${misc:Depends},
   node-foo (=1.0.0)
   node-ta (= 1.2.3),
   node-tb (= 0.3.4)


Of course, update debian/copyright with components copyrights.


You must build components, and if a component is a build dependency of main package, add a link to node_modules directory. Example:

    dh $@

    mkdir node_modules
    cd ta && dh_auto_build; cd -
    cd tb && dh_auto_build; cd -
    ln -s ta node_modules/ta
    ln -s tb node_modules/tb


Install all components into /usr/lib/nodejs:

ta/index.js usr/lib/nodejs/ta/
ta/package.json usr/lib/nodejs/ta/
tb/index.js usr/lib/nodejs/tb/
tb/package.json usr/lib/nodejs/tb/
index.js usr/lib/nodejs/test/
package.json usr/lib/nodejs/test/

Other files

Check if it is useful or not to export component README, changelog,...


Nothing special here except that you can build a test for each component if main component test seems not enough. It is important to write tests that really require every embedded component, so autopkgtest will prove that install is good.

The end

When build is OK, of course verify using debc that install looks good (package are really usable.

Using git subtree to track multiple upstream (optional)

git subtree could be used to track multiple upstream, and allow easier cherry picking. Let suppose that you want to package node-acorn with subpackage node-acorn-node.

you should first add the remote acorn and remote acorn-node

git remote add upstream-acorn
git remote add upstream-acorn-bigint
git remote add upstream-acorn-import-meta
git remote add upstream-acorn-node

Fetch all

git fetch --all

If not done create a fake upstream branch for main package

git checkout gitidofupstreamcorn
git checkout -b upstreamdebian