nodejs-cli-aur-packager

Node.js CLI → AUR packaging

Overview

Package a Node.js CLI using the npm registry tarball as the upstream source. Prefer reusing the build artifacts already published to npm, and avoid rebuilding from source, in order to improve stability and reproducibility.

Applicable scope

Judge in the following order:

1. Confirm the target is a CLI tool, and that npm package.json contains bin。
2. Confirm the target version has already been published to the npm registry.
3. Confirm the tarball already contains runnable artifacts, such as bin/、dist/。
4. If the tarball does not contain artifacts, a full build process must be run, or it depends on a native compilation toolchain, do not directly apply this skill; switch to a source-build approach.
5. If the target is a pure library rather than a CLI, usually do not use this skill; library packages are generally handled separately according to nodejs-* rules.

Core rules

• Prefer packaging from the npm tarball, not from the GitHub source repository.
• Verify the npm metadata first, then write PKGBUILD。
• By default skip the upstream postinstall. Only manually reproduce the necessary parts after you have read the script and confirmed it is necessary and safe for the packaging result.
• Do not assume there is only one bin entry point; when there are multiple entry points, generate a wrapper script for each entry point.
• Do not assume the tarball definitely has LICENSE file; check the actual file names and paths first.
• Do not claim the package works unless you have actually run makepkg --printsrcinfo and makepkg -f。

Standard workflow

1. Collect upstream metadata

First run:

npm view "<npm包名>@<版本>" version dist.tarball bin license engines dependencies optionalDependencies bundledDependencies scripts --json

At minimum confirm:

• Actual version number
• tarball URL
• bin entry point
• License type
• engines.node
• Runtime dependencies
• Whether there is postinstall

2. Download the tarball and compute the checksum

Run:

curl -sL "<tarball-url>" -o "/tmp/<name>-<ver>.tgz"
sha256sum "/tmp/<name>-<ver>.tgz"

Write the resulting hash into sha256sums. Do not keep SKIP。

3. Inspect the tarball contents

At minimum confirm whether these items exist:

• package/package.json
• package/bin/... or bin the actual entry file pointed to
• package/dist/...(if the entry depends on build artifacts)
• package/LICENSE or a similar file
• package/node_modules/ whether it is already bundled

If the tarball already contains node_modules/ or the npm metadata declares bundledDependencies, usually there is no need to run npm install。

4. Decide whether prepare() needs to install dependencies

Handle according to the following rules:

• No runtime dependencies, and the tarball is self-contained: omit prepare()。
• Has runtime dependencies, and the tarball does not contain node_modules/: in prepare() , install the runtime dependencies.
• There is postinstall: read the script first; by default continue to use --ignore-scripts。

Recommended prepare()：

prepare() {
    cd "${srcdir}/package"

    npm install \
        --cache "${srcdir}/npm-cache" \
        --omit=dev \
        --ignore-scripts \
        --no-audit \
        --no-fund
}

Prefer using --omit=dev, do not write the old-style --production。

5. Write PKGBUILD

Default approach:

• arch=('any')
• depends=('nodejs>=<engines.node 的下限>')
• Only prepare() when it calls npm, add makedepends=('npm')
• Install the main body into /usr/lib/nodejs-${pkgname} such a stable path
• Use /usr/bin/<命令名> a wrapper script to invoke the Node entry point

Basic form of the wrapper script:

#!/bin/sh
exec node /usr/lib/nodejs-${pkgname}/bin/<入口文件> "$@"

If bin points to another location, write it according to the real path; do not assume it is definitely at bin/。

If there are multiple bin, generate a script for every executable command.

When writing source :

• No scope:https://registry.npmjs.org/<npmname>/-/<npmname>-<pkgver>.tgz
• With scope:https://registry.npmjs.org/@scope/<name>/-/<name>-<pkgver>.tgz

When you need a directly reusable template, read references/pkgbuild-template.md。

6. Generate .SRCINFO

Execute:

makepkg --printsrcinfo > .SRCINFO

Do not hand-write .SRCINFO。

7. Local build verification

At minimum execute:

makepkg -f

It is recommended to continue with two types of verification:

1. Check the artifact contents:

bsdtar -tf "<生成的包文件>.pkg.tar.zst"

1. Check whether the CLI is executable:

makepkg -si
<命令名> --help

Package name and path decisions

• Pure CLI tools: prefer a command-line-oriented package name, as long as it does not conflict with existing AUR packages.
• Pure libraries: usually use nodejs-<name>。
• scope packages: the AUR package name does not need to retain the scope, but the scope path must be retained in the tarball URL.
• Even if the AUR package name is a bare command name, the installation directory can still use the nodejs-${pkgname} style.

High-risk points

• postinstall modifies user directories, shell configuration, or telemetry settings
• bin is an object rather than a single string
• The tarball is missing a LICENSE file
• engines.node The lower bound is higher than Arch's current stable version
• Runtime dependencies are not installed, causing the CLI to crash immediately on startup

Output requirements after completion

When the task is complete, explicitly return:

• PKGBUILD path
• .SRCINFO path
• .pkg.tar.zst path (if already built)
• Actual sha256
• Verification commands actually executed
• Remaining risks and recommended additional tests