Chainguard Libraries for JavaScript overview

Chainguard Libraries for JavaScript is a major ecosystem supported by Chainguard Libraries. The JavaScript ecosystem consists of thousands of open source projects from the communities around JavaScript, TypeScript, Node.js, React, Vue.js, Angular, Svelte, Next.js, Express, and many others.

Chainguard Libraries for JavaScript provides access to a growing collection of popular Javascript packages rebuilt from source. New releases of packages requested by customers are built and added to the index by an automated system. These libraries can also be consumed through the Chainguard Repository, which provides a single endpoint for package retrieval and supports configurable security policies for both Chainguard-built and upstream packages.

Background

The main public repository for JavaScript packages is the npm Registry. Launched in 2010, the npm Registry has grown to become the largest software registry in the world, hosting over three million packages. It serves as the central hub for open source JavaScript libraries, tools, and frameworks, supporting a vibrant and rapidly evolving ecosystem. The registry is widely used by developers for both client-side and server-side JavaScript projects, and its scale and history make it a critical resource for modern application development.

It is the default repository in all commonly used build tools from the JavaScript community, including npm, pnpm, Yarn, and Yarn Berry, and uses the npm repository format. Chainguard Libraries for JavaScript covers many of the open source artifacts found in the npm Registry.

You can use Chainguard Libraries for Javascript with your repository manager, such as JFrog Artifactory or Sonatype Nexus.

Runtime requirements

The runtime requirements for packages available from Chainguard Libraries for JavaScript are identical to the requirements of the original upstream project. For example, if a package retrieved from the npm Registry requires Node.JS v22 or higher, the same Node.JS v22 requirement applies to the package from Chainguard Libraries for JavaScript. The same applies to JavaScript, Typescript, or React versions, as well as any other requirements of the original upstream project.

Technical details

The username and password retrieved with chainctl are required to access the Chainguard Libraries for JavaScript repository. The URL for the repository is:

https://libraries.cgr.dev/javascript/

The URL does not expose a browsable directory structure.

The Chainguard Libraries for JavaScript repository is exposed through the Chainguard Repository endpoint for JavaScript libraries. It uses the npm repository protocol and serves both libraries that Chainguard has rebuilt from verifiable source and, when configured, packages proxied from the public npm registry under configurable policy controls. All packages served through this endpoint are subject to Chainguard security controls such as malware scanning and a configurable cooldown period for newly published upstream versions.

Even with upstream fallback enabled, the repository does not include every package from npm. Packages may be unavailable when:

• No verifiable source code is available. For example, malicious or proprietary packages where Chainguard cannot validate the source.
• The package is blocked by Chainguard or your organization’s policies. For example, packages flagged as malware or packages currently within the configurable cooldown period.

We recommend configuring the Chainguard Repository (or a repository manager that proxies it) as the primary registry for all JavaScript dependency resolution. This ensures your builds always prefer Chainguard‑built libraries first and automatically fall back to policy‑protected upstream packages when a Chainguard build is not yet available.

You can continue to use additional registries alongside Chainguard for needs outside this scope, such as your own private or scoped packages from npm or another internal registry.

Configure this endpoint globally through a repository manager for centralized access control across your organization, or use it for direct access from individual build tools. If you prefer to manage your own npm fallback rather than using the built-in upstream fallback, refer to the global configuration documentation for setup guides per repository manager.

Updating lockfile hashes

Existing JavaScript lockfiles usually contain upstream integrity hashes. Because Chainguard rebuilds packages from verified source, those hashes must be updated before reinstalling. Use chainctl libraries update-hashes to update them in place. Learn more in Build configuration.

For a step-by-step walkthrough of moving an existing project to Chainguard Libraries, check out the JavaScript migration guide.

If you install through a repository manager, refer to Global configuration.

When the upstream fallback is enabled, build pinning keeps a version you pulled from upstream stable after Chainguard publishes its own build, so you don’t have to update these hashes again unexpectedly.

CVE remediation

Chainguard Libraries for JavaScript includes the CVE Remediation feature. Remediated packages carry an appended prerelease identifier of -cgr.N. For example, a remediated build of example-package version 4.17.21 is published as example-package@4.17.21-cgr.1.

Unlike Python and Java, JavaScript remediation does not rely on version precedence. Because -cgr.N is an npm prerelease identifier, npm semver resolution does not treat it as newer than the base version, so a normal range such as ^4.17.21 never matches it. Instead, remediation operates on the resolved dependency tree in your lockfile.

Preview available remediations by running chainctl libraries remediate, then adopt them by running the same command with --apply. When applied, the command walks the lockfile and updates each eligible package to the corresponding -cgr.N version. The change depends on where the package sits in your dependency tree: for a direct dependency, the command sets the exact -cgr.N version in package.json; for a transitive dependency, it adds an override or resolution rule that your package manager supports. In both cases, it also updates the lockfile. Re-run the command after every install or dependency update so that newly resolved entries are evaluated.

Remediated artifacts are served through the standard JavaScript endpoint at https://libraries.cgr.dev/javascript/. For how remediation handles transitive dependencies and repeated package occurrences, see CVE remediation.

Provenance and attestations

Chainguard Libraries for JavaScript include SLSA provenance with signed attestations. These attestations cryptographically link each package to the Chainguard Factory build environment, providing verifiable proof of where and how each package was produced. Provenance attestations follow the npm attestation standard. The Chainguard publisher identity is verifiable via the Sigstore signing certificate embedded in the attestation bundle, which links back to https://issuer.enforce.dev,
the Chainguard OIDC issuer.

You can verify a package tarball in a single command using chainctl:

chainctl libraries verify PACKAGE-VERSION.tgz

You can also verify a lockfile directly, without installing dependencies:

chainctl libraries verify package-lock.json

Supported lockfiles are package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, yarn.lock, and bun.lock.

Refer to Verification for setup and usage details.

Verify attestation manually

Alternatively, you can verify a specific package’s provenance attestation manually using cosign, which is useful for debugging or integrating individual steps into custom workflows. In the following commands, replace PACKAGE and VERSION with the package name and version (for example, axios-mock-adapter and 1.17.0):

Download the tarball

curl -L -H "Authorization: Bearer $(chainctl auth token --audience=libraries.cgr.dev)" \
  "https://libraries.cgr.dev/javascript/PACKAGE/-/PACKAGE-VERSION.tgz" \
  -o PACKAGE-VERSION.tgz

Extract the SLSA provenance bundle

curl -H "Authorization: Bearer $(chainctl auth token --audience=libraries.cgr.dev)" \
  "https://libraries.cgr.dev/javascript/-/npm/v1/attestations/PACKAGE@VERSION" | \
  jq -c '.attestations[] | select(.predicateType | contains("slsa")) | .bundle' \
  > PACKAGE-provenance.sigstore.json

Verify the attestation was signed by Chainguard

cosign verify-blob-attestation \
  --bundle PACKAGE-provenance.sigstore.json \
  --type slsaprovenance1 \
  --certificate-oidc-issuer=https://issuer.enforce.dev \
  --certificate-identity-regexp="^https://issuer.enforce.dev/" \
  --check-claims=false \
  PACKAGE-VERSION.tgz

If this command returns an error, ensure you are using the latest version of cosign.

A successful verification returns:

Verified OK

The --certificate-oidc-issuer and --certificate-identity-regexp flags confirm the attestation was signed by Chainguard.

Retrieve SBOMs

To save the available SPDX SBOM and verified SLSA provenance bundle during verification, use chainctl libraries verify --output-attestations with --output-dir. Refer to Download JavaScript SBOMs and attestations for examples, output paths, and the trust status of each file.

Chainguard Libraries for JavaScript also include Software Bills of Materials (SBOMs) in SPDX format.

To check whether an SBOM is available for a package, use npm show with the dist.sboms field:

npm show PACKAGE@VERSION dist.sboms

To retrieve the SBOM directly:

curl -H "Authorization: Bearer $(chainctl auth token --audience=libraries.cgr.dev)" https://libraries.cgr.dev/javascript/-/npm/v1/sbom/spdx/PACKAGE@VERSION

Replace PACKAGE and VERSION with the package name and version (for example, react-router and 7.11.0).

Upstream fallback policy and controls

Chainguard Libraries for JavaScript supports an optional built-in fallback to the upstream npm Registry, managed through the Chainguard Repository. By default, the endpoint serves only Chainguard-built packages. When the upstream fallback is enabled, upstream packages are subject to additional security controls before being served.

Learn about managing fallback and cooldown controls in the Libraries overview.

Note: Upstream fallback has been tested against pnpm v11. When using pnpm, we recommend pnpm v11 or newer.