npmExecuteScripts

Handles JavaScript dependency installation via npm, yarn or pnpm and basic npm commands.

Description

Lock file detection:

• If package-lock.json is found → runs npm ci
• If yarn.lock.json is found → runs yarn install --frozen-lockfile
• If pnpm-lock.yaml is found → runs pnpm install --frozen-lockfile
• If no lock file is found → defaults to npm install and continues execution

Only the install command uses the detected package manager (npm, yarn, or pnpm). All other commands (e.g., run, pack, publish) are executed via the npm CLI, regardless of which lock file is detected.
Rationale: In the Piper environment, using the npm CLI for non-install commands provides sufficient functionality without requiring additional CLI dependencies. Supporting yarn or pnpm for these commands was deemed unnecessary due to lack of added benefit.
If your project contains multiple package.json files (i.e., multi module projects), install command will be run in every directory where the package.json file is found. One can use buildDescriptorList or buildDescriptorExcludeList (more details below) to override the default behaviour.
Currently multimodule pnpm projects are not supported. For such projects , it is necessary to use buildDescriptorList parameter pointing to package.json in root folder.

Build with private dependencies from a repository

If your build has scoped/unscoped dependencies from a private repository you can include a .npmrc into the source code repository as below (replace the @privateScope:registry value(s) with a valid private repo url) :
@privateScope:registry=https://private.repository.com/ //private.repository.com/:username=${PIPER_VAULTCREDENTIAL_USER} //private.repository.com/:_password=${PIPER_VAULTCREDENTIAL_PASSWORD_BASE64} //private.repository.com/:always-auth=true registry=https://registry.npmjs.org PIPER_VAULTCREDENTIAL_USER and PIPER_VAULTCREDENTIAL_PASSWORD_BASE64 (Base64 encoded password) are the username and password for the private repository and are exposed are environment variables that must be present in the environment where the Piper step runs or alternatively can be created using : vault general purpose credentials

Usage

We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.

JenkinsCommand Line

library('piper-lib-os')

npmExecuteScripts script: this

piper npmExecuteScripts

Outputs

Output type	Details
commonPipelineEnvironment	custom/buildSettingsInfo custom/npmBuildArtifacts

Parameters

Overview - Step

Name	Mandatory	Additional information
script	(yes)	reference to Jenkins main pipeline script
buildDescriptorExcludeList	no
buildDescriptorList	no
buildSettingsInfo	no
createBOM	no
createBuildArtifactsMetadata	no
defaultNpmRegistry	no
install	no
packBeforePublish	no
production	no
publish	no
repositoryPassword	no	pass via ENV or Jenkins credentials
repositoryUrl	no
repositoryUsername	no	pass via ENV or Jenkins credentials
runScripts	no
scriptOptions	no
verbose	no	activates debug output
virtualFrameBuffer	no

Overview - Execution Environment

Orchestrator-specific only

These parameters are relevant for orchestrator usage and not considered when using the command line option.

Name	Mandatory	Additional information
containerCommand	no
containerShell	no
dockerEnvVars	no
dockerImage	no
dockerName	no
dockerOptions	no
dockerPullImage	no
dockerVolumeBind	no
dockerWorkspace	no
stashContent	no

Details

buildDescriptorExcludeList

List of build descriptors and therefore modules to exclude from execution of the npm scripts. The elements can either be a path to the build descriptor or a pattern.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	- deployment/**
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

buildDescriptorList

List of build descriptors and therefore modules for execution of the npm scripts. The elements have to be paths to the build descriptors. If set, buildDescriptorExcludeList will be ignored.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_buildDescriptorList (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

buildSettingsInfo

build settings info is typically filled by the step automatically to create information about the build settings that were used during the npm build . This information is typically used for compliance related processes.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_buildSettingsInfo (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/buildSettingsInfo

containerCommand

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

containerShell

Jenkins-specific: Used for proper environment setup.

Allows to specify the shell to be executed for container with containerName.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

createBOM

Create a BOM xml using CycloneDX.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

createBuildArtifactsMetadata

metadata about the artifacts that are build and published , this metadata is generally used by steps downstream in the pipeline

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

defaultNpmRegistry

URL of the npm registry to use. Defaults to https://registry.npmjs.org/

back to overview

Scope	Details
Aliases	npm/defaultNpmRegistry
Type	string
Mandatory	no
Default	$PIPER_defaultNpmRegistry (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerEnvVars

Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].

back to overview

Scope	Details
Aliases	-
Type	map[string]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerImage

Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	node:lts-bookworm
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerName

Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	node
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerOptions

Docker options to be set when starting the container.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerPullImage

Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerVolumeBind

Jenkins-specific: Used for proper environment setup.

Volumes that should be mounted into the docker container.

back to overview

Scope	Details
Aliases	-
Type	map[string]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerWorkspace

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

install

Run npm install or similar commands depending on the project structure.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

packBeforePublish

used for executing npm pack first, followed by npm publish. This two step maybe required in two cases. case 1) When building multiple npm packages (multiple package.json) please keep this parameter true and also see buildDescriptorList or buildDescriptorExcludeList to choose which package(s) to publish. case 2)when you are building a single npm (single package.json in your repo) / multiple npm (multiple package.json) scoped package(s) and have npm dependencies from the same scope.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

production

used for omitting installation of dev. dependencies if true

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

publish

Configures npm to publish the artifact to a repository.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

repositoryPassword

Password for the repository to which the project artifacts should be published.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_repositoryPassword (if set)
Secret	yes
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/npmRepositoryPassword commonPipelineEnvironment:   reference to: custom/repositoryPassword

repositoryUrl

Url to the repository to which the project artifacts should be published.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_repositoryUrl (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/npmRepositoryURL commonPipelineEnvironment:   reference to: custom/repositoryUrl

repositoryUsername

Username for the repository to which the project artifacts should be published.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_repositoryUsername (if set)
Secret	yes
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/npmRepositoryUsername commonPipelineEnvironment:   reference to: custom/repositoryUsername

runScripts

List of additional run scripts to execute from package.json.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_runScripts (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

script

The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

back to overview

Scope	Details
Aliases	-
Type	Jenkins Script
Mandatory	yes
Default
Secret	no
Configuration scope	☐ parameter ☐ general ☐ steps ☐ stages
Resource references	none

scriptOptions

Options are passed to all runScripts calls separated by a '--'. './piper npmExecuteScripts --runScripts ci-e2e --scriptOptions '--tag1' will correspond to 'npm run ci-e2e -- --tag1'

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_scriptOptions (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

stashContent

Jenkins-specific: Used for proper environment setup.

Specific stashes that should be considered for the step execution.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	- source
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

verbose

verbose output

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

virtualFrameBuffer

(Linux only) Start a virtual frame buffer in the background. This allows you to run a web browser without the need for an X server. Note that xvfb needs to be installed in the execution environment.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none