Build Configuration

The configuration for the use of Chainguard Libraries depends on your build tools, continuous integration, and continuous deployment setups.

At a high level adopting the use of Chainguard Libraries consists of the following steps:

• Remove local caches on workstations and CI/CD pipelines. This step ensures that any libraries that were already sourced from other repositories are requested again and the version from Chainguard Libraries is used instead of other binaries.
• Change configuration to access Chainguard Libraries via your repository manager after the changes from the global configuration are implemented.

These changes must be performed on all workstations of individual developers and other engineers running relevant application builds. They must also be performed on any build server such as Jenkins, TeamCity, GitHub or other infrastructure that builds the applications or otherwise downloads and uses relevant libraries.

JFrog Artifactory

Build configuration to retrieve artifacts from Artifactory typically requires you to authenticate and use the identity token in the configuration of your build tool.

Follow the steps from the global configuration to determine URL and authentication details.

Sonatype Nexus Repository

Build configuration to retrieve artifacts from Nexus may require authentication. Use your username and password for Nexus in your build tool configuration.

Follow the steps from the global configuration to determine URL and authentication details.

Direct access

Build configuration to retrieve artifacts directly from the Chainguard Libraries for JavaScript repository at https://libraries.cgr.dev/javascript/ requires authentication with username and password from a pull token as detailed in access documentation.

npm

npm is the default package manager for Node.js, widely used for managing JavaScript dependencies and scripts. It allows developers to install, share, and manage packages for their projects. For more details, see the npm documentation.

With npm, you declare JavaScript package dependencies in a package.json file and separated into development and runtime dependencies. The following snippet shows a minimal example with a couple of dependencies each:

{
  "dependencies": {
    "@emotion/react": "^11.14.0",
    "@emotion/styled": "^11.14.0",
    "@fontsource/roboto": "^5.1.1",
    "node": "^22.18.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^7.1.5",
  },
  "devDependencies": {
    "@eslint/js": "^9.14.0",
    "@types/react": "^18.3.18",
    "@types/react-dom": "^18.3.5"
  }
}

By default, npm retrieves packages from the npm Registry at https://registry.npmjs.org and stores them locally in the node_modules directory of the project after running npm install. This operation also creates the package-lock.json file.

Note that dependency versions are typically declared with the ^ before the version string. This indicates higher, compatible versions, following the semantic versioning scheme of the package are used automatically. For example, the declaration of version ^22.18.0 for node, actually results in the use of version 22.20.0 or even a higher version once available and npm install is run.

Any dependency or dependency version changes require another install and therefore an update to the lock file. The lock file also encodes the checksum values in the integrity field and the download URL in the resolved field for each module.

To change a project to use Chainguard Libraries for JavaScript, set the registry URL to point to your repository manager in your user .npmrc file:

npm config set registry https://repo.example.com:8443/repository/javascript-all/

The command results in the following line in the .npmrc file:

registry=https://repo.example.com:8443/repository/javascript-all/

Refer to the npmrc documentation for alternative configurations, for example per project or globally, and details for configuring authentication.

Example URLs:

• JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all/
• Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
• Direct access: https://libraries.cgr.dev/javascript/

To change the packages, remove the node_modules directory and the package-lock.json file and run the npm install command again.

Now you can proceed with your development and testing.

Minimal example project

Use the following steps to create a minimal example project for npm with Chainguard Libraries for JavaScript.

mkdir npm-example
cd npm-example
npm init -y

For testing purposes, you can use direct access and environment variables as detailed in the access documentation. Once the environment variables are set, the following steps configure registry access with authentication in the .npmrc file in the current project directory:

export token=$(echo -n "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" | base64 -w 0)

npm config set registry https://libraries.cgr.dev/javascript/ --location=project
npm config set //libraries.cgr.dev/javascript/:_auth "${token}" --location=project

Note that the trailing slash in the registry URL is required, and that setting username and _password instead of auth with a token does not work with npm. The -w 0 option for base64 is required and supported by the GNU coreutils versions included in most operating systems.

Add dependencies for your project into the package.json file to test retrieval from Chainguard Libraries, build the project, and list the dependencies:

npm add commander@4.1.1
npm install
npm list

Following this, find the downloaded package in node_modules/commander. The commands also result in the creation of the lock file package-lock.json, which contains the source URL for each package in the resolved field.

Adjust the registry configuration to use your repository manager and add any other desired packages for further testing.

pnpm

pnpm is a fast, disk space-efficient package manager for JavaScript, designed as an alternative to npm and Yarn. For more information, see the pnpm documentation.

With pnpm, you declare JavaScript package dependencies in a package.json file and separated into development and runtime dependencies. The following snippet shows a minimal example with a couple of dependencies each:

{
  "dependencies": {
    "@emotion/react": "^11.14.0",
    "@emotion/styled": "^11.14.0",
    "@fontsource/roboto": "^5.1.1",
    "node": "^22.18.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^7.1.5",
  },
  "devDependencies": {
    "@eslint/js": "^9.14.0",
    "@types/react": "^18.3.18",
    "@types/react-dom": "^18.3.5"
  }
}

By default, pnpm retrieves the packages the npm Registry at https://registry.npmjs.org and stores them locally in the node_modules directory of the project after running pnpm install. This operation also creates the pnpm-lock.yaml file.

Note that dependency versions are typically declared with the ^ before the version string. This indicates higher, compatible versions, following the semantic versioning scheme of the package, are used automatically. For example, the declaration of version ^22.18.0 for node, actually results in the use of version 22.20.0 or even a higher version once available and pnpm install is run.

Any dependency or dependency version changes require another install and therefore an update to the lock file. The lock file also encodes the checksum values in the integrity field and other information for each module.

To change a project to use Chainguard Libraries for JavaScript, set the registry URL to point to your repository manager in your user .npmrc file:

pnpm config set registry https://repo.example.com:8443/repository/javascript-all/

The command results in the following line in the .npmrc file:

registry=https://repo.example.com:8443/repository/javascript-all/

Refer to the pnpm registry documentation for alternative configurations, for example per project or globally, and details for configuring authentication.

Example URLs:

• JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all/
• Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
• Direct access: https://libraries.cgr.dev/javascript/

To change the packages, remove the node_modules directory and the pnpm-lock.yaml file and run the pnpm install command again.

Now you can proceed with your development and testing.

Minimal example project

Use the following steps to create a minimal example project for pnpm with Chainguard Libraries for JavaScript.

mkdir pnpm-example
cd pnpm-example
pnpm init

For testing purposes, you can use direct access and environment variables as detailed in the access documentation. Once the environment variables are set, the following steps configure registry access with authentication in the .npmrc file in the current project directory:

export token=$(echo -n "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" | base64 -w 0)

pnpm config set registry https://libraries.cgr.dev/javascript/ --location=project
pnpm config set //libraries.cgr.dev/javascript/:_auth "${token}" --location=project

Note that the -w 0 option for base64 is required and supported by the GNU coreutils versions included in most operating systems. To avoid the use of base64, which can behave differently across operating systems, you can alternatively set username and _password instead of auth with a token.

pnpm config set //libraries.cgr.dev/javascript/:username "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}" --location=project
pnpm config set //libraries.cgr.dev/javascript/:_password "${CHAINGUARD_JAVASCRIPT_TOKEN}" --location=project

Also note that the trailing slash in the registry URL is required.

Add dependencies for your project into the package.json file to test retrieval from Chainguard Libraries, build the project, and list the dependencies:

pnpm add commander@4.1.1
pnpm install
pnpm list

Following this, find the downloaded package in node_modules/.pnpm/commander@4.1.1 and node_modules/commander. The commands also result in the creation of the lock file pnpm-lock.yaml, which contains the source URL for each package in the tarball field.

Adjust the registry configuration to use your repository manager and add any other desired packages for further testing.

Yarn

Yarn is a popular package manager for JavaScript projects, offering fast, reliable, and secure dependency management as an alternative to npm. It is widely used for managing project dependencies, scripts, and workflows in Node.js and other JavaScript development environments. For more details, refer to the Yarn documentation.

This section applies to modern versions of Yarn, also known as Yarn Berry, with versions 2.x and higher. If you are using Yarn 1.x refer to the Yarn Classic section.

With Yarn, you declare JavaScript package dependencies in a package.json file and separated into different scoped dependencies such as development and runtime dependencies. The following block shows a minimal example with react and node as main runtime dependencies and eslint as development dependency:

{
  "name": "yarn-berry-example",
  "packageManager": "yarn@4.10.3",
  "dependencies": {
    "node": "^22.20.0",
    "react": "^19.1.1"
  },
  "devDependencies": {
    "eslint": "^9.36.0"
  }
}

By default, Yarn retrieves the packages from the registry at https://registry.yarnpkg.com and stored locally folder .yarn in the users home directory after running yarn. Specific packages are linked into the project. This operation also creates the yarn.lock file.

Note that dependency versions are typically declared with the ^ before the version string. This indicates higher, compatible versions, following the semantic versioning scheme of the package, are used automatically. For example, the declaration of version ^22.18.0 for node, actually results in the use of version 22.20.0 or even a higher version once available and yarn is run.

Any dependency or dependency version changes require another install and therefore an update to the lock file. The lock file also encodes the checksum values in the checksum field.

To change a project to use Chainguard Libraries for JavaScript, set the registry URL to point to your repository manager in your project .yarnrc.yml file:

yarn config set npmRegistryServer https://repo.example.com:8443/repository/javascript-all

The command results in the following line in the .yarnrc.yml file:

npmRegistryServer: "https://repo.example.com:8443/repository/javascript-all"

Refer to the config set documentation for more details such as authentication support.

Example URLs:

• JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all
• Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all
• Direct access: https://libraries.cgr.dev/javascript

To change the packages, run the yarn command again. This forces an updated of all packages from the new registry and regeneration of the lock file.

Now you can proceed with your development and testing.

Minimal example project

Use the following steps to create a minimal example project for yarn with Chainguard Libraries for JavaScript. The script sets the policy to use the latest stable release of Yarn.

mkdir yarn-berry-example
cd yarn-berry-example
yarn policies set-version stable
yarn init

For testing purposes, you can use direct access and environment variables as detailed in the access documentation. Once the environment variables are set, the following steps configure registry access with authentication in the .yarnrc.yml file in the current project directory:

export authInfo="${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}"

yarn config set npmRegistryServer https://libraries.cgr.dev/javascript
yarn config set 'npmRegistries["//libraries.cgr.dev/javascript"].npmAuthIdent' "${authInfo}"
yarn config set 'npmRegistries["//libraries.cgr.dev/javascript"].npmAlwaysAuth' "true"

Note the following details:

• The authInfo token is passed as authentication identity npmAuthIdent and only uses the username and password values from the pull token separated by colon without any further encoding.
• Setting npmAlwaysAuth is required.

Add dependencies for your project into the package.json file to test retrieval from Chainguard Libraries, build the project, and list the dependencies:

yarn add commander@4.1.1
yarn install
yarn info

Following this, find the downloaded package in the local shared cache. The commands also result in the creation of the lock file yarn.lock, which contains the source URL for each package in the archiveUrl parameter of the resolution field.

Adjust the registry configuration to use your repository manager and any add other desired packages for further testing.

Yarn Classic

Yarn Classic is the legacy 1.x release of Yarn.

With Yarn, you declare JavaScript package dependencies in a package.json file and separated into different scoped dependencies such as development and runtime dependencies. The following block shows a minimal example with react and node as main runtime dependencies and eslint as development dependency:

{
  "name": "yarn-classic-example",
  "version": "1.0.0",
  "description": "A minimal example project for using yarn classic",
  "main": "index.js",
  "author": "Chainguard",
  "license": "MIT",
  "private": false,
  "dependencies": {
    "node": "^22.18.0",
    "react": "^19.1.1"
  },
  "devDependencies": {
    "eslint": "^9.36.0"
  }
}

By default, Yarn retrieves the packages from the registry at https://registry.yarnpkg.com and stores them locally in the node_modules directory of the project after running yarn. This operation also creates the yarn.lock file.

Note that dependency versions are typically declared with the ^ before the version string. This indicates higher, compatible versions, following the semantic versioning scheme of the package, are used automatically. For example, the declaration of version ^22.18.0 for node, actually results in the use of version 22.20.0 or even a higher version once available and yarn is run.

Any dependency or dependency version changes require another install and therefore an update to the lock file. The lock file also encodes the checksum values in the integrity field and the download URL in the resolved field for each module.

To change a project to use Chainguard Libraries for JavaScript, set the registry URL to point to your repository manager in your .npmrc file:

cat > .npmrc << EOF
registry=https://repo.example.com:8443/repository/javascript-all
EOF

Example URLs:

• JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all
• Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all
• Direct access: https://libraries.cgr.dev/javascript

Note that you can also use the yarn config set registry command to set the registry in the .yarnrc file, however this approach does not support authentication as typically required for repository managers as well as for direct access to Chainguard Libraries for JavaScript.

Refer to the .yarnrc documentation for more details.

To change the packages, remove the node_modules directory and the yarn.lock file and run the yarn command again. This forces a new download of all packages from the new registry and regeneration of the lock file. Alternatively, you can run yarn upgrade to update all dependencies to their latest allowed versions and regenerate the lock file.

Now you can proceed with your development and testing.

Minimal example project

Use the following steps to create a minimal example project for yarn with Chainguard Libraries for JavaScript.

mkdir yarn-classic-example
cd yarn-classic-example
yarn init -y

For testing purposes, you can use direct access and environment variables as detailed in the access documentation. Once the environment variables are set, the following steps configure registry access with authentication in the .npmrc file directory:

export token=$(echo -n "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" | base64 -w 0) 
cat > .npmrc << EOF
registry=https://libraries.cgr.dev/javascript/
//libraries.cgr.dev/javascript/:_auth="$token"
//libraries.cgr.dev/javascript/:always-auth=true
EOF

Note the following details:

• Using yarn configuration files such as .yarnrc and commands like yarn config set registry does not work with authentication details, and the proposed approach with .npmrc file is preferable.
• The token token is passed as authentication token _auth and uses the username and password values from the pull token separated by colon in base64 encoding. Note that the -w 0 option for base64 is required and supported by the GNU coreutils versions included in most operating systems.
• Setting always-auth is required.
• The trailing slash in the registry URL and authentication references to it is required.

Add dependencies for your project into the package.json file to test retrieval from Chainguard Libraries, build the project, and list the dependencies:

yarn add commander@4.1.1
yarn install
yarn list

Following this, find the downloaded package in the node_modules directory. The commands also result in the creation of the lock file yarn.lock, which contains the source URL for each package in the resolved field.

Adjust the registry configuration to use your repository manager and add any other desired packages for further testing.

Bun

Bun is a fast, all-in-one JavaScript runtime, bundler, and package manager designed as an alternative to Node.js tooling. It provides an integrated package manager that is compatible with the npm ecosystem.

With Bun you declare dependencies in a package.json file just like npm. The following snippet shows a minimal example:

{
  "dependencies": {
    "@emotion/react": "^11.14.0",
    "@emotion/styled": "^11.14.0",
    "@fontsource/roboto": "^5.1.1",
    "node": "^22.18.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^7.1.5"
  },
  "devDependencies": {
    "@eslint/js": "^9.14.0",
    "@types/react": "^18.3.18",
    "@types/react-dom": "^18.3.5"
  }
}

By default Bun installs packages from the npm Registry at https://registry.npmjs.org and stores them locally in the node_modules directory after running bun install. Bun creates a binary lockfile named bun.lock to record resolved versions and checksums.

Note that dependency versions are typically declared with ^ to allow compatible newer releases under semantic versioning. For example, ^22.18.0 for node can result in 22.20.0 or higher when bun install runs.

Any dependency or version changes require running bun install again, which updates the lockfile.

To switch a project to use Chainguard Libraries for JavaScript, point Bun at your repository manager. Add the registry configuration to the bunfig.toml file of your project: `

[install]
# set default registry as a string
registry = "https://repo.example.com:8443/repository/javascript-all/"

Alternatively you can use an .npmrc file.

You can also temporarily override for install:

bun install --registry=https://repo.example.com:8443/repository/javascript-all/

Refer to Bun documentation for additional registry and authentication options.

Example registry URLs:

• JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all/
• Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
• Direct access: https://libraries.cgr.dev/javascript/

To apply the registry change to an existing project, remove node_modules and the bun.lock file and run:

bun install

This forces packages to be re-fetched from the configured registry and regenerates the lockfile. Now you can continue development and testing with Chainguard Libraries.

Minimal example project

Use the following steps to create a minimal example project for bun with Chainguard Libraries for JavaScript.

mkdir bun-example
cd bun-example
bun init -y

For testing purposes, you can use direct access and environment variables as detailed in the access documentation. Once the environment variables are set, the following steps configure registry access with authentication in the bunfig.toml file in the current project directory:

cat > bunfig.toml << EOF
[install.registry]
url = "https://libraries.cgr.dev/javascript/"
username = "$CHAINGUARD_JAVASCRIPT_IDENTITY_ID"
password = "$CHAINGUARD_JAVASCRIPT_TOKEN"
EOF

Note that the trailing slash in the registry URL is required.

Add dependencies for your project into the package.json file to test retrieval from Chainguard Libraries, build the project, and list the dependencies:

bun add commander@4.1.1
bun install
bun pm ls

Following this, find the downloaded package in node_modules/commander. The commands also result in the creation of the lock file bun.lock, which contains the source URL for each package in the packages section.

Adjust the registry configuration to use your repository manager and add any other desired packages for further testing.