Put shared settings, such as the private registry for your company scope, in the project .npmrc that lives in git. Put credentials only in your per-user ~/.npmrc, scoped to a specific registry, and never commit them. npm resolves these files in priority order, so a user setting can override a global one.
The four npmrc files
The npm documentation names four files: a per-project file in the project root, a per-user file at ~/.npmrc, a global file, and a built-in file that ships with npm. They are ini-formatted key and value lists, and environment variables can be substituted with the dollar and braces form. The project file only applies when you run npm in that project root, and it is not read in global mode.
That gives a clean rule of thumb.
| What | Where | Committed? |
|---|---|---|
| Registry for a company scope | Project .npmrc | Yes |
| Flags the team agrees on | Project .npmrc | Yes |
| Auth tokens | User ~/.npmrc | Never |
| Token reference by variable | Project .npmrc | Yes, the variable name only |
Scope credentials to a registry
The documentation is explicit that settings such as _authToken must be scoped to a specific registry by prefixing a URI fragment. This ensures npm never sends credentials to the wrong host. An unscoped token line is called out as bad config in the docs, while a line prefixed with the registry host is the good form.
Scoped registry mapping works the same way: a line that maps your company scope to a registry URL sends only packages under that scope there. Everything else keeps using the default registry unless your team has a proxy.
New-laptop steps
- Clone the repo and read its .npmrc before running anything.
- Ask your onboarding contact which registry hosts the private scope and how to get a token.
- Prefer a read-only, short-lived token for development. If your registry supports granular tokens, use them. See npm granular access tokens.
- Add the token to your user file, scoped to the registry host.
- Run npm config list to review the effective settings.
- Check that the user .npmrc is not inside any git repository.
What to avoid
Do not paste a token into a project file "just to get unblocked". Git history keeps it, and so do CI logs. If it happens, revoke the token first, then clean up. Our guide to a live secret in your logs covers the order of operations.
Also be wary of a project .npmrc from a repository you did not write. It can redirect where packages come from. Reading it takes thirty seconds.
Where Safeguard fits
Safeguard can do the inventory and watching for you. Its SBOM and dependency scanning lists what a repository actually pulls in, reachability analysis helps separate reachable findings from noise, and policies can gate a pull request. You can try a free scan on a repository to see the output.
Quick check
Can I put my token in the project .npmrc if the repo is private?
Avoid it. Private repos get cloned, forked and exported. Use a variable reference or the user file instead.
How do I see which file a setting came from?
Run npm config list to review the settings npm will use, then compare them with the files described above.
Sources
Last reviewed: 19 October 2026.
