npm plugin

The npm plugin can be used for Node.js projects that use npm (or Yarn) as the package manager.

Keys

This plugin provides the following unique keys.

npm-include-node

Type

bool

Description

Whether to download and include the Node.js binaries and its dependencies in the part.

If this key is set to true, then the npm-node-version key must also be set.

npm-node-version

Type

str

Description

The version of Node.js to download and include in the part.

Accepted version formats:

  • Exact version, such as "20.12.2"

  • Major version, such as "20"

  • Minor version, such as "20.12"

  • LTS code name, such as "lts/iron"

  • Latest mainline version, such as "node"

When setting a loose version identifier, the plugin selects the latest version that satisfies the provided version range. If the version picked by the plugin doesn’t publish binaries for the target architecture, the plugin picks the nearest version that both satisfies the version range and also publishes binaries for the target architecture.

Required if the npm-include-node key is set to true.

Warning

With the nvm utility, you can set system to use the system Node.js package, but this is unsupported by this plugin, as it uses upstream Node.js binaries.

Also, the iojs specifier is unsupported in this plugin, as the iojs project was merged back to Node.js in 2015. Using a very old iojs runtime poses a significant security hazard. If a part requires a JavaScript runtime from this era, consider migrating it to a modern Node.js runtime.

Attributes

This plugin supports the self-contained build attribute. Declaring this attribute enables offline builds by blocking all npm registry access and installing dependencies from pre-cached tarballs.

Parts that produce dependencies should use the npm-use plugin to publish their tarballs to a shared cache.

In self-contained builds, package-lock.json is ignored. Dependencies are resolved at build time from cached tarballs produced by other parts. The npm-include-node option is not supported with this build attribute. Node.js must be provided by a build snap or build package.

Examples

The following example declares a part using the npm plugin. In this example, we show how you may build the terser utility (a utility for compressing and obfuscating JavaScript code). It uses the latest mainline stable version of Node.js and includes a copy of the Node.js runtime inside the final package.

parts:
    app:
        plugin: npm
        source: https://github.com/terser/terser
        source-type: git
        npm-include-node: true
        npm-node-version: "node"

Another example that shows how to install an application that is published to the npm registry but does not require a Node.js runtime to run.

parts:
    app:
        plugin: npm
        source: https://registry.npmjs.org/esbuild/-/esbuild-0.21.3.tgz
        source-type: tar
        npm-include-node: false
        build-snaps:
        # use Node.js Snap during the build-time only
            - node