Skip to main content

npm, pnpm and yarn

Map a package scope to one broker project, then use a token to install packages from that project.

Prerequisites​

You need a running broker, a project with an npm source, and a token that can read the package. Replace <broker-host>, <project>, <scope> and <package> with your HTTPS host, project slug, package scope without the leading @, and an available package name. Include a nondefault port in the host. Run the section for your chosen client in the application directory.

Token kinds​

See token kinds in the access model for token boundaries, expiry and revocation.

Supply NPM_TOKEN through your terminal environment or CI secret settings before installing. It is a client recipe variable, not a broker runtime setting. Keep the literal ${NPM_TOKEN} placeholder in committed config; never replace it with a token in a committed file. Avoid shell tracing and commands that print authentication configuration.

The registry is https://<broker-host>/<project>/npm/. Scope the credential to this host and path. A package scope mapping chooses a registry; it does not grant project access.

npm​

Add these lines to .npmrc beside package.json. Other package scopes continue using your existing registry settings.

@<scope>:registry=https://<broker-host>/<project>/npm/
//<broker-host>/<project>/npm/:_authToken=${NPM_TOKEN}

Install a package, then use the lock file on subsequent CI runs:

npm install '@<scope>/<package>'
npm ci

pnpm​

Keep only the scope mapping in the application's .npmrc. pnpm 12 ignores repository-controlled auth settings, including an _authToken containing an environment placeholder:

@<scope>:registry=https://<broker-host>/<project>/npm/

Put the credential reference in your user-level ~/.npmrc, outside the application repository. Keep the placeholder literal; pnpm expands it from your environment:

//<broker-host>/<project>/npm/:_authToken=${NPM_TOKEN}

Add a dependency and commit the resulting pnpm-lock.yaml. Use the locked install in CI:

pnpm add '@<scope>/<package>'
pnpm install --frozen-lockfile

Yarn Classic (1.x)​

Add these lines to .npmrc; Classic reads npm-style registry credentials:

@<scope>:registry=https://<broker-host>/<project>/npm/
//<broker-host>/<project>/npm/:_authToken=${NPM_TOKEN}
always-auth=true

The top-level always-auth=true applies to all registries in this config, including non-broker scopes. Review this effect if the application uses multiple registries. Yarn 1 on Node 24 may print a DEP0169 deprecation warning.

Add a package and keep yarn.lock for subsequent installs:

yarn add '@<scope>/<package>'
yarn install --frozen-lockfile

Yarn Berry (2.x and later)​

Use .yarnrc.yml instead of .npmrc. Scope names under npmScopes omit @. Keep the token on the project registry entry and set npmAlwaysAuth so package reads carry it.

npmScopes:
  <scope>:
    npmRegistryServer: 'https://<broker-host>/<project>/npm/'
npmRegistries:
  '//<broker-host>/<project>/npm/':
    npmAlwaysAuth: true
    npmAuthToken: '${NPM_TOKEN}'

Add a package, then use an immutable install with the committed lock file:

yarn add '@<scope>/<package>'
yarn install --immutable

Verify the install​

Confirm the dependency appears in the client's lock file and that its archive is downloaded from the project's broker URL. Berry records a package resolution rather than an archive URL in its lock. Test a second install from the lock with an empty client cache; disable Berry's mirror and global cache for authentication checks (enableMirror: false and enableGlobalCache: false). Scope mapping affects package resolution; an old lock may still refer to a previous registry and needs review after a registry change.

For 401, check token placement, host/path, expiry and revocation. For 403, check grants and token scope. An inaccessible project or package can return 404. See Composer authentication failures for the shared status meanings.

Publishing​

This version serves npm installs but rejects npm package writes with HTTP 405 after access checks. Publishing through npm, pnpm, Yarn Classic or Yarn Berry is therefore unavailable. A token with scope write does not enable an unsupported registry operation. Do not use an install token for a publishing job; keep any publishing credentials separate when a supported publishing endpoint becomes available.

Continue with GitHub Actions or GitLab CI for secret placement and client caches, or Composer setup for PHP packages.