Global configuration

JavaScript and npm package consumption in a large organization is typically managed by a repository manager. Commonly used repository manager applications are JFrog Artifactory, Sonatype Nexus Repository, and others. The repository manager acts as a single point of access for developers and development tools to retrieve the required libraries.

If your organization uses the upstream fallback feature of Chainguard Repository, you can configure your repository manager with a single upstream pointed at https://libraries.cgr.dev/javascript/. This is the recommended setup. The Chainguard Repository handles fallback and policy enforcement; your repository manager handles local caching and access control. Chainguard also retrieves packages from the public npm Registry on your behalf when upstream fallback is enabled. This includes protections such as malware detection and a cooldown period for newly published packages.

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

• Configure your environment to use https://libraries.cgr.dev/javascript/ as the single upstream source for JavaScript package retrieval. This can be done either:
  • As a remote repository in your repository manager, or
  • Directly in your JavaScript build configuration (for example, npm, pnpm, or yarn).
• Additional steps depend on your visibility and validation goals and can include the following optional measures:
  • Remove all cached libraries in existing proxy repositories. This step allows you to validate which libraries are not available from Chainguard Libraries and ensures they are retrieved through Chainguard for evaluation.
  • Remove any repositories that are no longer desired or necessary. Depending on your library requirements, this step can result in removal of some proxy repositories or simplification of your repository configuration.

Adopting the use of a repository manager is the recommended approach to minimize complexity. If your organization does not use a repository manager, refer to the direct access documentation for build tools.

Manually managing fallback

Chainguard recommends using the Chainguard Repository’s built-in upstream fallback rather than configuring a public registry fallback in your repo manager. Configuring your own fallback bypasses the protection that the Chainguard Repository provides.

However, if upstream fallback is not enabled or you prefer to manage your own fallback ordering, you can configure https://libraries.cgr.dev/javascript/ as a remote repository alongside your npm upstream, and combine them in a virtual or group repository with Chainguard as the first priority. The per-tool instructions on this page follow this pattern.

Updating lockfile hashes

If you are migrating an existing JavaScript project to Chainguard Libraries through a repository manager, your lockfile likely contains integrity hashes generated against packages previously downloaded from npm or through your repository manager. The chainctl libraries update-hashes command automates lockfile hash updates for all supported JavaScript lockfile formats.

When you are using a repository manager, pass the full repository manager URL with --registry-url and authenticate with one of the supported methods: --username and --password, --token, or a .netrc entry for the registry host. For example:

chainctl libraries update-hashes \
  --registry-url https://repo.example.com:8443/repository/javascript-all/ \
  --token "$REPO_TOKEN"

After updating the lockfile, keep your repository manager configuration in place and reinstall through the same repository manager endpoint to apply the updated hashes.

Learn more in the Build configuration page and in the chainctl docs.

Cloudsmith

Cloudsmith supports npm registries for proxying and hosting. Refer to the npm registry documentation and the npm Upstream documentation for Cloudsmith for more information. Cloudsmith supports combining repositories by defining multiple upstream repositories.

Initial configuration

Use the following steps to configure a repository with the Chainguard Libraries for JavaScript repository as an upstream.

Configure a javascript-all repository. This repository acts as a single access point for JavaScript packages and may also include private packages or additional upstream sources, depending on your configuration.

1. Log in as a user with administrator privileges.
2. Select the Repositories tab near the top of the screen.
3. On the Repositories page, click + New repository.
4. Enter the name javascript-all for your new repository. The name should include javascript to identify the ecosystem. This convention helps avoid confusion since repositories in Cloudsmith are multi-format.
5. Select a storage region that is appropriate for your organization and infrastructure.
6. Click + Create Repository.

Configure an upstream proxy for the Chainguard Libraries for JavaScript repository:

1. Click the name of the new javascript-all repository on the repositories page to configure it.
2. Access the Upstreams tab and click + Add Upstream Proxy.
3. Configure an upstream proxy with the format npm and the following details:
   • Name javascript-chainguard
   • Priority 1
   • Proxy URL https://libraries.cgr.dev/javascript/
   • Mode Cache and Proxy
   • Add the Username and Password value from Chainguard Libraries access in Authentication Settings
4. Click Create Upstream Proxy.

If you are manually managing fallback, you can add an additional upstream proxy for the public npm registry with a lower priority than javascript-chainguard.

Use this setup for initial testing with Chainguard Libraries for JavaScript. For production usage, add the javascript-chainguard upstream proxy to your production repository.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Select the Packages tab.
2. Click Push/Pull Packages.
3. Choose the format NPM.
4. Refer to the Pull Package tab.
5. Note the registry URL and syntax from the code snippets for npm. For example, the URL for the registry in the example organization is https://npm.cloudsmith.io/example/javascript-all/.
6. Note that authentication is using an authentication token and the syntax for npm in the example organization is //npm.cloudsmith.io/example/javascript-all/:_authToken=YOUR-API-KEY

Use the provided code snippets directly for your use with npm, or adjust as necessary for other JavaScript build and packaging tools. Find relevant details in the Build Configuration and specific packaging tool documentation.

Use the following steps to retrieve the necessary API key as an authentication token for the registry access:

1. Click on your user name at the top right corner.
2. Select Personal API keys.
3. Authenticate again in the Confirm access dialog.
4. Create a new token or refresh the existing one in case you lost the token value.

JFrog Artifactory

JFrog Artifactory supports npm repositories for proxying and hosting, and virtual repositories to combine them. Refer to the npm registry documentation for Artifactory for more information.

Initial configuration

Use the following steps to add Chainguard Libraries for JavaScript as a remote repository:

1. Log in as a user with administrator privileges.
2. Click Administration in the top navigation bar.
3. Select Repositories in the left hand navigation.

Configure a remote repository for the Chainguard Libraries for JavaScript repository:

1. Click Create a Repository and choose the Remote option.
2. Select Npm as the Package type.
3. Set the Repository Key to javascript-chainguard.
4. Set the URL to https://libraries.cgr.dev/javascript/.
5. Set User Name and Password / Access Token to the values as retrieved with chainctl.
6. Click Create Remote Repository.

Create a virtual repository, or add the remote repository to an existing virtual repository used for npm packages. A virtual repository may also include private npm packages or additional upstream sources, depending on your configuration.

1. Click Create a Repository → Virtual.
2. Select Npm.
3. Set key to javascript-all.
4. Add javascript-chainguard.
5. Click Create Virtual Repository.

If you are manually managing fallback, you can configure an additional npm remote repository with lower priority.

Use this setup for initial testing with Chainguard Libraries for JavaScript. For production usage add the javascript-chainguard repository to your production virtual repository.

Advanced settings for redirect handling

Chainguard Libraries uses Cloudflare R2 storage, meaning tarball downloads from libraries.cgr.dev return a 302 redirect to a different host. Without additional configuration, Artifactory may cache the redirect response instead of the actual tarball, causing npm integrity checksum failures at install time.

To prevent this:

1. Apply the following settings to your Artifactory javascript-chainguard remote repository, within in the Advanced tab:
   • Enable Bypass HEAD Requests — prevents Artifactory from sending HEAD requests that may not be handled correctly by redirect-based registries.
   • Disable Lenient Host Authentication — disabling this setting ensures credentials are not forwarded across the redirect.
   • Enable Cookie Management - this setting is optional, but recommended by JFrog for remote repositories that involve redirects.
2. Clear the corrupted cached tarballs: in Artifactory, right-click the javascript-chainguard repository and click Zap Caches, then re-run your install.
   • Alternatively, you could delete specific corrupted .tgz artifacts from the remote cache, rather than deleting all, before re-running the install.

Validate the remote repository

After creating and configuring the javascript-chainguard remote repository, validate that Artifactory is successfully proxying through to Chainguard before proceeding. Because Artifactory falls back to the upstream npm registry when a connection to a remote repository fails, a misconfigured repository may silently resolve packages from npm rather than Chainguard — and the build will succeed without any visible error.

Common sources of misconfiguration include invalid or expired credentials, an incorrect or incomplete URL, and misconfigured settings in the Advanced tab. The Artifactory Test button on the repository configuration screen is not a reliable indicator; it may fail for a correctly configured repository, and may pass for an incorrectly configured one. Instead, use the following steps to verify that fetching an artifact through Artifactory produces the same checksum as fetching it directly from libraries.cgr.dev.

1. Fetch the artifact directly from Chainguard and compute its checksum, using the same credentials you configured in Artifactory. This example uses picocolors-1.1.1. You can substitute any artifact you know to be available.

curl -sSf -L \
  -u "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" \
  https://libraries.cgr.dev/javascript/picocolors/-/picocolors-1.1.1.tgz \
  | openssl dgst -sha512 -binary | base64

2. Fetch the same artifact through the Artifactory remote repository and compute its checksum:

curl -sSf -L \
  -H "Authorization: Bearer ${ARTIFACTORY_TOKEN}" \
  https://<artifactory-host>/artifactory/api/npm/javascript-chainguard/picocolors/-/picocolors-1.1.1.tgz \
  | openssl dgst -sha512 -binary | base64

Replace artifactory-host with your Artifactory instance hostname, and replace ${ARTIFACTORY_TOKEN} with your Artifactory identity token.

3. If your configuration includes a virtual repository combining javascript-chainguard with a public npm fallback, test that as well:

curl -sSf -L \
  -H "Authorization: Bearer ${ARTIFACTORY_TOKEN}" \
  https://<artifactory-host>/artifactory/api/npm/javascript-all/picocolors/-/picocolors-1.1.1.tgz \
  | openssl dgst -sha512 -binary | base64

The checksums returned by the commands must match.

If the checksum from the Artifactory remote or virtual repository differ from the direct fetch, or if the Artifactory fetch fails entirely, review the following before proceeding:

• URL: The remote repository URL must be set to https://libraries.cgr.dev/javascript/.
• Credentials: You may need to regenerate your pull token with chainctl auth pull-token --repository=javascript and update the Artifactory repository credentials. Expired tokens fail silently.
• Advanced tab settings: Confirm that Bypass HEAD Requests is enabled and Lenient Host Authentication is disabled.

Do not proceed to virtual repository setup or build configuration until the checksums match.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Click Administration in the top navigation bar.
2. Select Repositories in the left hand navigation.
3. Select the Virtual tab in the repositories view.
4. Locate the javascript-all repository.
5. Hover over the row and click the … in the last column on the right.
6. Select Set Me Up in the dialog.
7. Click Generate Token & Create Instructions.
8. Copy the generated token value to use as the password for authentication.
9. Click Generate Settings.
10. Copy the value from a url field. They are all identical. For example, https://exampleorg.jfrog.io/artifactory/javascript-all/ with exampleorg replaced with the name of your organization.

Use the URL of the virtual repository in the build configuration and build a first test project. In a working setup the chainguard remote repository contains all libraries retrieved from Chainguard.

Sonatype Nexus Repository

Sonatype Nexus Repository allows for merging multiple remote repositories as a repository group. The below instructions are based on the Nexus documentation for npm.

Initial configuration

For initial testing and adoption it is advised to create a separate proxy repository for the Chainguard Libraries for JavaScript repository, and include it in a repository group:

1. Log in as a user with administrator privileges.
2. Access the Server administration and configuration section with the gear icon in the top navigation bar.

Configure a proxy repository for the Chainguard Libraries for JavaScript repository:

1. Select Repository - Repositories in the left hand navigation.
2. Click Create repository.
3. Select the npm (proxy) recipe.
4. Provide a new name javascript-chainguard.
5. In the Proxy - Remote storage input add the URL https://libraries.cgr.dev/javascript/.
6. In HTTP - Authentication with the Authentication type Username, provide the username and password values as retrieved with chainctl.
7. Click Create repository.

Create a repository group, or add to an existing repository group:

1. Select Repository - Repositories in the left hand navigation.
2. Click Create repository.
3. Select the npm (group) recipe.
4. Provide a new name javascript-all.
5. In the section Group - Member repositories, move the new repository javascript-chainguard to the right to include it in the group. Position javascript-chainguard at the top of the list using the arrow controls.

Repository groups can include multiple repositories, such as hosted repositories for private packages or additional proxy repositories. In a typical configuration, the Chainguard repository is placed first to ensure packages are retrieved through Chainguard when available.

If you are manually managing fallback, you can configure an additional npm proxy repository and add it to the group after javascript-chainguard.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Click Browse in the Welcome view or the browse icon (cube) in the top navigation bar.
2. Locate the URL column for the javascript-all repository group and click copy. For example, https://repo.example.com/repository/javascript-all/ with repo.example.com replaced with the hostname of your repository manager.
3. Copy the URL in the dialog.
4. Use your configured username and password unless Security - Anonymous Access - Access - Allow anonymous users to access the server is activated. Details vary based on your configured authentication system.

Use the URL of the repository group, such as https://repo.example.com/repository/javascript-all/ in the build configuration and build a first test project. In a working setup the javascript-chainguard proxy repository contains all libraries retrieved from Chainguard.

Google Artifact Registry

Google Artifact Registry (GAR) is not an officially supported repository manager for Chainguard Libraries for JavaScript. However, it has been shown to work with the following configuration.

Configure two GAR remote repositories, with upstream validation disabled on the second:

• First remote repository: javascript-chainguard pointing to https://libraries.cgr.dev/javascript with upstream validation enabled
• Second remote repository: javascript-chainguard-upstream pointing to https://libraries.cgr.dev/javascript-upstream with upstream validation disabled.

When using artifactregistry-auth, note that it only injects credentials for repositories explicitly listed in your .npmrc. Ensure you add a credentials entry for the javascript-chainguard-upstream repository alongside your existing javascript-chainguard entry, otherwise you will receive 404s for upstream-fallback packages.