Some node modules are rather small and sometime are dependency of only one package. To avoid having many node modules, qa.debian.org 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 npmjs.com) 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:

[DEFAULT]
component = [ 'ta', 'tb' ]

version=4
  
opts="searchmode=plain,pgpmode=none" \
 https://registry.npmjs.org/test \
 https://registry.npmjs.org/test/-/test-(\d[\d\.]*)@ARCHIVE_EXT@ group

opts="searchmode=plain,pgpmode=none,component=ta" \
 https://registry.npmjs.org/ta \
 https://registry.npmjs.org/ta/-/ta-(\d[\d\.]*)@ARCHIVE_EXT@ group

opts="searchmode=plain,pgpmode=none,component=tb" \
 https://registry.npmjs.org/tb \
 https://registry.npmjs.org/tb/-/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
debian/
ta/
tb/
index.js
package.json
...

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

debian/control

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},
         nodejs
Provides:
   node-foo (=1.0.0)
   node-ta (= 1.2.3),
   node-tb (= 0.3.4)
...

debian/copyright

Of course, update debian/copyright with components copyrights.

debian/rules

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

%:
    dh $@

override_dh_auto_build:
    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
    dh_auto_build

debian/install

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,...

autopkgtest

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 https://github.com/acornjs/acorn
git remote add upstream-acorn-bigint https://github.com/acornjs/acorn-bigint
git remote add upstream-acorn-import-meta https://github.com/acornjs/acorn-import-meta/
git remote add upstream-acorn-node https://github.com/browserify/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