Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Publishing

Scopes, Registries and .npmrc

Understand scoped packages, private and mirror registries, dist-tags, access control and the .npmrc, .yarnrc.yml and pnpm settings that point tools at them.

So far we published to "the registry" as if there were only one. In practice a team talks to several: the public npm registry, a private company registry, perhaps a local mirror in CI. Which one a package comes from is decided by configuration, and getting that configuration wrong is a classic source of both broken builds and security problems. This lesson explains scopes, registries, dist-tags and the config files that tie them together.

Configuration files and commands appear as read-only snippets. The runnable examples are plain-Node stand-ins that parse .npmrc text and resolve a registry the way the tools do.

What a registry is

A registry is an HTTP service. Given a package name it returns a JSON document (the packument) listing every version, its dependencies, its tarball URL and its integrity hash, and it serves the tarballs themselves. Anything that speaks that protocol can be a registry: the public registry at registry.npmjs.org, GitHub Packages, GitLab, Artifactory, Nexus, Verdaccio (a lightweight open-source one), or a pull-through cache.

Yarn and pnpm use the same protocol, so a package published with npm installs with Yarn and the other way round.

Scopes

A scope is a namespace written as @scope/name. On the public registry a scope belongs to a user or an organization, which prevents name clashes (@acme/utils cannot be taken by someone else) and lets teams hand out publish rights per scope.

Scopes matter for configuration too: you can send one scope to a different registry while everything else keeps using the default one.

INI
# .npmrc  (project root, next to package.json)
@acme:registry=https://npm.acme.example/
//npm.acme.example/:_authToken=${ACME_NPM_TOKEN}

Now npm install @acme/ui asks npm.acme.example, while npm install lodash still goes to the public registry. The second line attaches a token to that host, read from an environment variable so the secret is never committed.

Never commit a real token. Reference an environment variable (${ACME_NPM_TOKEN}) in the project .npmrc and put the real value in the user ~/.npmrc or in your CI secret store. If a token leaks, revoke it first and clean up afterwards.

Dependency confusion

If your company has a private package called acme-internal-utils (unscoped) and an attacker publishes a public package with the same name and a higher version, a misconfigured install may fetch the attacker's copy. Defenses: use a scope for every internal package, claim your scope on the public registry, and route that scope explicitly to the private registry as above.

Where configuration lives

npm reads .npmrc files in this order, later ones winning: built-in defaults, the global file, the user file (~/.npmrc), the project file, then environment variables and command-line flags. Yarn Berry uses .yarnrc.yml:

YAML
# .yarnrc.yml
npmScopes:
  acme:
    npmRegistryServer: "https://npm.acme.example/"
    npmAuthToken: "${ACME_NPM_TOKEN}"

pnpm reads .npmrc (and pnpm-workspace.yaml for newer workspace settings), so the first example works for pnpm unchanged.

Useful settings you will meet often:

Setting Purpose
registry Default registry URL
@scope:registry Registry for one scope
//host/:_authToken Credentials for a host
save-exact=true Save 1.2.3 instead of ^1.2.3
engine-strict=true Fail install when engines is not satisfied
ignore-scripts=true Do not run install scripts
audit-level Minimum severity for audit failures

This stand-in parses a small .npmrc, expands environment variables and answers "which registry serves this package and with what token?".

Node.js Stand-in: resolve the registry for a package

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Dist-tags

A dist-tag is a movable label pointing at a version. Every package has latest, which is what npm install name installs. You can add more: beta, next, canary, legacy.

Terminal
npm publish --tag next                 # publish without moving "latest"
npm dist-tag add demo@2.0.0-rc.1 next  # label an existing version
npm dist-tag ls demo
npm install demo@next                  # consumers opt in
npm dist-tag add demo@2.0.0 latest     # promote when ready

Publishing a pre-release without --tag would move latest to it, so newcomers would get an unstable build. npm actually refuses to publish a pre-release version without an explicit tag in recent versions for that reason.

This stand-in models the tag table:

Node.js Stand-in: dist-tags are just a name-to-version map

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Access control and private packages

  • On the public registry, scoped packages can be private (a paid feature) with npm access and teams of collaborators.
  • Use granular access tokens limited to specific packages and to read-only or read/write, with an expiry date.
  • Require two-factor authentication for publishing; in CI prefer trusted publishing (an OIDC identity from GitHub Actions or GitLab) over a stored token, which also enables provenance badges.
  • npm owner ls demo lists maintainers; npm access manages who can read or write a package.

Running your own registry is realistic: Verdaccio runs from one Docker container, proxies the public registry for anything it does not hold, and caches tarballs so CI installs are faster and survive an upstream outage (see speeding up installs).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does @acme:registry=https://npm.acme.example/ in .npmrc do?

    A scope-specific registry setting routes just that scope; everything else keeps using the default registry.
  2. 2. Why should internal packages use a scope?

    A scope you own cannot be claimed by an attacker, and routing it to your registry removes the ambiguity.
  3. 3. What is a dist-tag?

    Dist-tags map names to versions. latest is the default; others like next let users opt in to pre-releases.
  4. 4. Where should a real registry token be stored for a CI job?

    Secrets belong in a secret store. The committed .npmrc refers to the environment variable only.

Summary

  • A registry is an HTTP service for package metadata and tarballs; npm, Yarn and pnpm share the protocol.
  • Scopes namespace packages and let you route one scope to a private registry.
  • Config comes from .npmrc (npm, pnpm) or .yarnrc.yml (Yarn Berry); keep tokens out of git.
  • Dist-tags such as latest and next control what a plain install gets.
  • Prefer granular tokens, two-factor authentication and trusted publishing.

Next: Lockfiles Explained