Did You say .npmrc?
If you worked long enough with npm chances are that you had to deal with .npmrc.
Maybe you had to setup a registry or maybe a proxy, in any case, I suspect that questions like “is this syntax correct?” or “did the setting get in?” popped in your mind.
How it comes that you need to configure npm at all?
Fair question. After all, npm downloads stuff and that’s pretty much it, isn’t it? Or is there something more?
While it’s correct saying that npm mainly downloads stuff, it’s not the only thing that npm does for you.
In fact, downloading stuff is just the beginning. Among other things, npm sets defaults (like initial licence, author, version), interacts with git, handles certificates and proxy, helps you explore packages, manages download strategies and so on and so on.
There are 148 config settings as per npm@9.6.5.
With such an abundance of settings, there may be some you like and some you don’t, the main point is: if you want to tune npm, .npmrc is here to satisfy your cravings.
In reality, .npmrc is not the only way to configure npm, you can use npm config, npm's cli flags and more.
Ready for .npmrc?
There are mainly two .npmrc files you may be interested in, the .npmrc file in the project folder and the .npmrc file in your user folder.
Both .npmrc files are parsed by npm/ini and the syntax goes like this:
# comment
; comment
setting-name-string="setting-value-string"
setting-name-bool=true
setting-name-number=15
setting-name-array=[]
You can use the .npmrc file in the project folder for project’s ad hocs.
One common use case can be adding scoped registries (for downloading packages from a private registry) while another interesting case could be using git-tag-version for avoiding commit and tag on npm version.
# Project folder npmrc
; When trying to install @my-private-pacakge
; npm will download from http://reg.example.com
@my-private-pacakge:registry=http://reg.example.com
; git settings
; on npm version do not tag nor commit
; npm version patch will only bump up package.json and
; package-lock.json
git-tag-version=false
Instead, you can use .npmrc in your user folder for settings across projects, like a proxy setup, editor, or init defaults.
# User folder npmrc
; changing defaults inits
; npm will use these values when you use
; npm init
init-author-name="Your name"
init-author-email="YourName@provider.com"
init-license="MIT"
init-version="0.0.0"
; do not use strict-ssl to validate certificate
; use CA certificates
; use a proxy when downloading packages
strict-ssl=false
cafile=~/.cafiles/
https-proxy=http://my.proxy.com
; save exact version on install
; npm i package-name will save the exact version
; in package.json you'll have
;
; "dependencies" : { "package-name" : "1.0.0"}
;
; Instead of
;
; "dependencies" : { "package-name" : "^1.0.0"}
;
save-exact=true
; chose the editor to use when
; npm edit package-name
editor="~/bin/subl"
With this distinction in mind, it should be easy to decide which .npmrc file to use.
Remember, the .npmrc file in the project folder for project’s ad hocs and the .npmrc in your user folder for settings across projects.
Did the settings get in?
Did it work? How do you check if the settings you’re using were effective? Well, you can use npm config ls -l.
As part of the output you’ll see the whole list of settings and if and where they’ve been overridden.
// Example for save-exact = true
// The setting is the .npmrc in ./todo-app
//
// npm config ls -l
; "default" config from default values
_auth = (protected)
access = null
all = false
allow-same-version = false
also = null
audit = true
audit-level = null
.
.
.
save-dev = false
; save-exact = false ; overridden by project
save-optional = false
save-peer = false
; save-prefix = "^" ; overridden by project
save-prod = false
.
.
.
; "user" config from /Users/You/.npmrc
//registry.npmjs.org/:_authToken = (protected)
; "project" config from /Users/You/todo-app/.npmrc
save-exact = true
save-prefix = ""
; "cli" config from command line options
long = true
Sure enough with npm config ls -l we can see the default config, the user config, the project config and the cli config .
The best part? ; save-exact = false ; overridden by project is there to tell you that yes, your project config is working.
Don’t you feel relief already?
Summary
Quick recap: we saw the two main .npmrc files, some use cases, the syntax supported by npm/ini and how to troubleshoot with npm config ls -l.
Using these concepts, It should be pretty straightforward for you to navigate the docs and play with .npmrc.