Configure an npm and pnpm proxy cache

BEFOREhttps://registry.npmjs.org

AFTERhttp://localhost:23333/npm/

npm, pnpm, Yarn, and Bun all use Depsilo’s /npm/ route. Depsilo forwards upstream packuments and tarballs, and clients still verify the integrity recorded in the lockfile.

The Portal only generates configuration

Select Node.js and the specific client in the Depsilo Portal to get configuration generated for the current address. The Portal only displays and copies instructions; it does not modify your machine or project files.

Configure the client

Merge this setting into .npmrc at the project root for npm or pnpm. Record the previous registry and preserve the other settings in that file:

.npmrc

registry=http://localhost:23333/npm/

Alternatively, run npm from the project root with an explicit configuration scope:

npm config set registry http://localhost:23333/npm/ --location=project
npm config get registry

Without --location=project, npm config set changes user configuration by default. Use --location=user only when you intend to affect all projects for that user, and back up that file first. See the npm configuration reference.

Yarn 2+ uses npmRegistryServer. A local HTTP instance also needs its hostname in unsafeHttpWhitelist:

.yarnrc.yml

npmRegistryServer: "http://localhost:23333/npm/"
unsafeHttpWhitelist:
  - localhost

HTTPS needs no HTTP whitelist entry for Depsilo; preserve settings for other sources. For a remote instance, replace localhost in the URL with a client-reachable address and put only its hostname in the whitelist, without the scheme, port, or path. Merge these settings into an existing .yarnrc.yml; if unsafeHttpWhitelist already exists, add the hostname to its list instead of overwriting the file. If a Portal-generated local HTTP whitelist includes :23333, omit that port.

Bun uses [install].registry in bunfig.toml:

bunfig.toml

[install]
registry = "http://localhost:23333/npm/"

Verify requests

1. Query package version metadata

   npm view is-number version

   Run this in the configured project directory. It does not write to node_modules or download the package tarball.

2. Confirm the traffic in Admin

   Open Admin → Access logs (/admin/logs) and match the request time, npm ecosystem, package, and status. A metadata log confirms only the metadata request. The client may reuse its local cache; without a new log, you have not verified that this request reached the server.

3. Verify the package artifact cache separately

   Follow Verify caching to obtain the tarball URL returned by the instance, download that artifact twice with curl, and check the two matching artifact logs. The first request can already be a hit if the cache is warm. Repeating npm install or npm view alone does not prove server-side reuse of the package file.

Common questions

Can I redirect only one scope?

Yes. Replacing registry with @scope:registry in .npmrc redirects only that scope; other dependencies use the default registry. For a shared entry point, set the project’s default registry and check whether any existing scope-specific registries still point elsewhere.

How should CI be configured?

Set the npm_config_registry environment variable; no lockfile changes are needed:

export npm_config_registry=http://depsilo.internal:23333/npm/
npm ci

Inside a container, localhost points at the container itself; use the address the runner can actually reach.

How do I roll back?

Restore the previous registry in the configuration scope you changed. If the setting did not exist, remove only the added registry entry and keep the other settings. Use npm config delete registry --location=project to remove a project entry. Do not keep a parallel public registry as a “rollback”.