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.

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.

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.

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 user .yarnrc file:

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

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

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

Refer to the .yarnrc documentation for more details.

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 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.