Configure the npm proxy cache for Nx Agents

The npm proxy cache reduces package download time by keeping public packages close to your Nx Agents. Configure your package manager to use the in-cluster registry before it installs dependencies.

Configure the default registry

Add the proxy registry to the .npmrc file at the workspace root or in your home directory:

registry=http://cache.npm.svc.cluster.local:4873/

If an existing project-level file sets registry, update that file. A user-level setting does not override a project-level setting.

Configure your package manager

npm and pnpm read the registry from .npmrc and need no other proxy cache configuration.

registry=http://cache.npm.svc.cluster.local:4873/

Yarn Classic reads the registry from .npmrc or .yarnrc. Use the same registry setting:

registry=http://cache.npm.svc.cluster.local:4873/

Yarn Modern reads the registry from npmRegistryServer in .yarnrc.yml:

npmRegistryServer: 'http://cache.npm.svc.cluster.local:4873/'

Route private packages

Map each private package scope to the registry that hosts it. The scoped setting takes precedence over the default proxy registry:

registry=http://cache.npm.svc.cluster.local:4873/
@<package-scope>:registry=https://<private-registry-host>/npm/

You can also write the scoped setting with the npm CLI:

npm config set @<package-scope>:registry https://<private-registry-host>/npm/

Configure package publishing

Set a publishing registry for each package that your workspace publishes. The publishConfig field in package.json keeps publish requests away from the proxy cache:

{
  "publishConfig": {
    "registry": "https://<publishing-registry-host>/npm/"
  }
}

A scoped registry in .npmrc also applies when you publish a package from that scope.

Configure an agent setup step

Add the registry settings before the dependency installation step in your launch template:

launch-templates:
  linux-medium:
    init-steps:
      - name: Configure the npm proxy cache
        script: |
          npm config set --location=user registry http://cache.npm.svc.cluster.local:4873/
          npm config set --location=user @<package-scope>:registry https://<private-registry-host>/npm/

Use a committed project-level configuration instead when the workspace already defines its registry in .npmrc or an equivalent file.

Understand cache behavior

The cache uses multiple replicas for reliability and local network access. A cold replica can still fetch a package from the upstream registry. The first request in an availability zone can therefore take longer than later requests.

For package manager details, see the npm .npmrc reference, pnpm settings, Yarn Classic configuration, and Yarn Modern configuration.