Where your dependencies actually come from, and how you prove you are allowed to have them.

Two lessons, written to the course standard. This folder is not about using npm โ€” npm install needs no explanation โ€” it is about the configuration layer underneath it, which is invisible until a project pulls from a private registry and then becomes most of the problem.

It belongs in tools/ by this folderโ€™s own test: if the config file has opinions in it, the opinions belong here. .npmrc is a config file that is almost entirely opinions.

The lessons

  1. Registries and the `.npmrc` File โ€” [Intermediate] โ€” what a registry is and why npm install lodash has to choose one; the precedence order across global, user and project .npmrc files and how they merge per key; what โ€œthe projectโ€ actually means (the local prefix, not the nearest .npmrc โ€” the monorepo trap); scoped registries routing one project to several servers; and ${VAR} substitution, which is what makes the file safe to commit.
  2. Authentication and Private Packages โ€” [Intermediate] โ€” tokens and where they should live; the four causes of a 401 in order of likelihood; GitHub Packagesโ€™ three rules; publishing safely with --dry-run; keeping credentials out of Docker layers; and Git URLs as dependencies, with what they cost.

The one thing to take away

Configuration belongs in the repository; credentials belong in the environment. A project .npmrc naming ${NODE_AUTH_TOKEN} is identical on a laptop and in CI โ€” the file says which variable, the environment supplies the value. Every recurring npm auth problem is a variation on that separation breaking down:

  1. The variable is not set in CI โ†’ the literal ${NODE_AUTH_TOKEN} is used โ†’ 401.
  2. The token is committed โ†’ the separation is gone โ†’ revoke it, immediately.
  3. COPY .npmrc in a Dockerfile โ†’ the credential ships inside the image.
  4. npm login on a laptop โ†’ a credential that exists in exactly one place and cannot be reproduced.

Reading the error before debugging it

StatusUsually meansCheck first
404wrong registrythe scope mapping โ€” @acme:registry=
401no credential sent, or invalidis the environment variable set?
403valid credential, insufficient permissionthe tokenโ€™s scopes โ€” read: vs write:packages

What is verified

Lesson 01 ships a runnable lab that redirects HOME into a sandbox so your real ~/.npmrc is never touched, contacts no registry, and deletes itself. It demonstrates from a live npm:

  • config files merging per key โ€” a project file overriding the registry while the user fileโ€™s save-exact survives;
  • npm config list naming the losing value and what beat it;
  • the local prefix rule, with project config applying from a subdirectory that has no .npmrc of its own;
  • three scopes resolving to three different registries;
  • ${VAR} expanding when set and staying a literal when unset โ€” the CI 401 in miniature;
  • npm refusing to print a token back, by design.

It was run twice and diffed to confirm the output reproduces.

Lesson 02 has no lab, because a real one would need real credentials โ€” it ships a read-only checklist instead, which publishes nothing and prints no secrets.

โ†‘ Back to Tools