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