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..npmrcis a config file that is almost entirely opinions.
The lessons
- Registries and the `.npmrc` File โ [Intermediate] โ what a registry is and why
npm install lodashhas to choose one; the precedence order across global, user and project.npmrcfiles 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. - 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:
- The variable is not set in CI โ the literal
${NODE_AUTH_TOKEN}is used โ 401. - The token is committed โ the separation is gone โ revoke it, immediately.
COPY .npmrcin a Dockerfile โ the credential ships inside the image.npm loginon a laptop โ a credential that exists in exactly one place and cannot be reproduced.
Reading the error before debugging it
| Status | Usually means | Check first |
|---|---|---|
| 404 | wrong registry | the scope mapping โ @acme:registry= |
| 401 | no credential sent, or invalid | is the environment variable set? |
| 403 | valid credential, insufficient permission | the 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-exactsurvives; npm config listnaming the losing value and what beat it;- the local prefix rule, with project config applying from a subdirectory that has no
.npmrcof 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.
Related
- Secret Management โ the general problem this is one instance of
- Pipeline Security โ credentials in a pipeline
- Git โ Git dependencies authenticate through Git, not through npm
- Environment Variables โ what
${VAR}substitution rests on - tools/ โ the parent folder
Software engineering
Infrastructure & security
AI & data
Computer science
Hardware & engineering