Node.js package guidelines - ArchWiki

Jump to content
From ArchWiki

This document covers standards and guidelines on writing PKGBUILDs for Node.js packages.

## Package naming

Tip: A custom `_pkgname` variable can be used instead of `pkgname`. This variable can generically be defined as follows: `_pkgname=${pkgname#nodejs-}`

Package names for Node.js libraries should start with a `nodejs-` prefix. For standalone applications, just use the program name.

## Source

npm provides a stable naming scheme for download URLs. PKGBUILD#source `source=()` array can use the following URL template:

    https://registry.npmjs.org/$_pkgname/-/$_pkgname-$pkgver.tgz

## Using npm

When installing with npm, add it as a build dependency:

    makedepends=('npm')

There is also usually no need to extract the tarball:

    noextract=("${_pkgname}-${pkgver}.tgz")

This is a minimal package function:

    package() {
        npm install -g --prefix "${pkgdir}/usr" "${srcdir}/${_pkgname}-${pkgver}.tgz"

        # npm gives ownership of ALL FILES to build user
        # https://bugs.archlinux.org/task/63396
        chown -R root:root "${pkgdir}"
    }

### Setting temporary cache

When npm processes `package.json` in order to build a package it downloads dependencies to its default cache folder at `$HOME/.npm`. To avoid littering user's home folder we can temporarily set a different cache folder with `--cache` flag.

Download dependencies to `${srcdir}/npm-cache` and install them in package directory:

    npm install --cache "${srcdir}/npm-cache"

Continue with packaging as usual:

    npm run packager

### Package contains reference to $srcdir/$pkgdir

npm unfortunately creates references to the source dir and the pkg dir, this is a known issue. However, you may remove those references manually since they are not used in any way.

All dependencies will contain a reference to `$pkgdir`, in the `_where` attribute. You can usually remove those attributes with some sed magic as follows:

    find "$pkgdir" -name package.json -print0 | xargs -r -0 sed -i '/_where/d'

Your main package will have some other references too. The easiest way to remove those is to remove all underscored properties, but that is not as easy with sed. Instead, you can use jq for similar results as follows:

    local tmppackage="$(mktemp)"
    local pkgjson="$pkgdir/usr/lib/node_modules/$_pkgname/package.json"
    jq '.|=with_entries(select(.key|test("_.+")|not))' "$pkgjson" > "$tmppackage"
    mv "$tmppackage" "$pkgjson"
    chmod 644 "$pkgjson"

Another place where you may find references to `$pkgdir` is the `man` attributes of packages. If you do not care about man pages (they will not be installed for dependencies anyway), you may delete them like this:

    find "$pkgdir" -type f -name package.json | while read pkgjson; do
        local tmppackage="$(mktemp)"
        jq 'del(.man)' "$pkgjson" > "$tmppackage"
        mv "$tmppackage" "$pkgjson"
        chmod 644 "$pkgjson"
    done

An example of all three of these techniques can be seen in readability-cliAUR.

## Using nvm

When a node.js-based application requires different version for building or packaging, then nvmAUR can be leveraged.

Warning: This applies only for building/packaging needs of the application and does not replace runtime dependency

Add it as a build dependency:

    makedepends=('npm' 'nvm')

nvmAUR uses `NVM_DIR` environment variable to look for its prefix, which is set to `$HOME/.nvm` if not specified before nvmAUR initialization.

You can use the following function to create and isolate your custom prefix from user's location:

    _ensure_local_nvm() {
        # let's be sure we are starting clean
        which nvm >/dev/null 2>&1 && nvm deactivate && nvm unload
        export NVM_DIR="${srcdir}/.nvm"

        # The init script returns 3 if version specified
        # in ./.nvrc is not (yet) installed in $NVM_DIR
        # but nvm itself still gets loaded ok
        source /usr/share/nvm/init-nvm.sh || [[ $? != 1 ]]
    }

This function should be called before interacting with nvmAUR, npm or any other Node.js based programs that should use the specified version.

### Example PKGBUILD usage

    prepare() {
        _ensure_local_nvm
        nvm install 14.15.0
    }

    build() {
        _ensure_local_nvm
        npm install
    }

Alternatively, bare `nvm install` will look for a version string in `.nvrc` file in the current directory.

An example of this usage can be seen in insomniaAUR. See PKGBUILD for more information.

Category:

- Arch package guidelines