Configuring npm (.npmrc)

Two ways to change a setting

npm's behaviour is controlled by configuration. You can set it from the command line, or write it into a .npmrc file (just "npm run configuration" — a plain text file of key=value lines). The command line is quick; a file is shareable and permanent.

Read and set configuration

Terminal 
$ npm config list      # what's currently set
$ npm config get registry
$ npm config set save-exact=true
In VS Code
  1. Run these in the integrated terminal
  2. npm config set writes to your personal ~/.npmrc
  3. Or create a .npmrc file in the project and type the settings by hand

A setting written to a file does the same thing as 'npm config set' — the file is just easier to share and review.

The three levels of .npmrc

npm reads .npmrc from several places, most specific winning:

  • Project — a .npmrc in the repo root. Committed to Git, so it applies to everyone on the project. Put shared, non-secret settings here.
  • User — ~/.npmrc in your home folder. Personal to you, and the right place for secrets like auth tokens.
  • Global — applies to the whole machine; rarely needed.

Settings actually worth setting

A project .npmrc with a couple of lines can prevent real problems:

save-exact=true
engine-strict=true
  • engine-strict=true — turns the engines field from a polite warning into a hard rule. This project's package.json requires Node >=22.12.0; with engine-strict on, npm would refuse to install on an older Node instead of just warning — catching the mismatch early.
  • save-exact=true — saves new packages with an exact version (6.4.2) instead of a caret range (^6.4.2), for teams that want zero version drift.

Pointing at a different registry

By default npm installs from the public registry. Companies sometimes run their own (or use a proxy/mirror). The registry setting redirects where packages come from: 

registry=https://registry.npmjs.org/
# only @my-company packages come from a private registry:
@my-company:registry=https://npm.my-company.com/
//npm.my-company.com/:_authToken=${NPM_TOKEN}

The middle line is a scoped registry: packages under @my-company/… come from the private server, while everything else still uses the public registry. The last line supplies the auth token for that private server.

Never commit a token. Notice the token above is ${NPM_TOKEN} — an environment variable, not the secret itself. Keep real tokens in your user-level ~/.npmrc or a CI secret, never in a project .npmrc that's committed to Git.

A common real use: GitHub Packages

Publishing or installing packages through GitHub Packages is a typical reason beginners first touch .npmrc — you point a scope at npm.pkg.github.com and add a token. The mechanism is exactly the scoped-registry + auth-token pattern above.

Up next: putting it all together in automation — using npm in CI/CD pipelines.

FAQ

Frequently Asked Questions

What is a .npmrc file?
A plain text configuration file of key=value lines that changes how npm behaves. It can live in your project (shared via Git), in your home folder (~/.npmrc, personal), or globally.
Where should I keep npm auth tokens?
In your user-level ~/.npmrc or a CI secret — never in a project .npmrc that gets committed. Reference them as an environment variable so the secret itself is never written to Git.
How do I make npm install from a different registry?
Set registry=https://your-registry/ in .npmrc, or scope it so only some packages use it: @scope:registry=https://your-registry/. Everything else still comes from the public registry.
What does engine-strict do?
Setting engine-strict=true turns the engines field from a warning into a hard rule — npm refuses to install on the wrong Node version instead of just warning, catching mismatches early.