PackagePass

.npmrc private registry

How to configure .npmrc for a private npm registry

A practical private registry setup for scoped npm packages, auth tokens, CI installs, and customer-facing packages.

Build configStart free

Implementation checklist

Use a scoped registry line so only your private scope is redirected.

Keep auth tokens in environment variables, not committed files.

Use always-auth for private scoped registries that require token checks on every request.

Test with npm whoami and npm view before debugging the package itself.

Step 1

Start with a scoped registry

The safest default is to route only your company scope to the private registry. That keeps public packages on the public npm registry while private packages install from the controlled registry.

.npmrc
@acme:registry=https://registry.packagepass.dev/npm/
//registry.packagepass.dev/npm/:_authToken=${PACKAGEPASS_INSTALL_TOKEN}
always-auth=true

Step 2

Keep the token outside source control

The .npmrc file can be committed when it references an environment variable. The actual token should live in the developer shell, CI secret store, or customer install portal.

  • Local development: export PACKAGEPASS_INSTALL_TOKEN before install.
  • GitHub Actions: store the token as an Actions secret.
  • Customer installs: issue a package-scoped install token instead of a repo invite.

PackagePass keeps install access, tokens, and audit events tied to the package workflow.

Step 3

Use PackagePass when access is not repo membership

Standard registries are fine when every installer is a teammate. PackagePass is built for the point where install access needs to map to customers, projects, previews, CI jobs, or generated SDK recipients.

PackagePass keeps install access, tokens, and audit events tied to the package workflow.

FAQ

Should I put registry=https://... at the top level?

Usually no. A top-level registry setting sends every dependency lookup to that registry. Scoped registry lines are cleaner for private packages because only the matching scope is routed.

Can I use this with pnpm, Yarn, and Bun?

Yes. npm-compatible registry configuration works across common JavaScript package managers, though Bun can also use bunfig.toml.

Next step

Turn the config into controlled package access.

PackagePass adds customer, project, user, and CI grants on top of normal npm-compatible installs.

Create a packagePrivate registry