The Role and Applications of `.npmrc` Files

The .npmrc file is a configuration file for npm (Node Package Manager) that defines npm’s behavior at different levels.
This blog post will explore its purpose, configuration hierarchy, and provide specific scenarios and examples of its use.

What is an .npmrc File?

An .npmrc file is a plain text configuration file used to store various npm-related settings. Through this file, you can customize npm’s behavior, such as specifying package sources, setting private repository credentials, configuring proxies, and more.

Configuration Hierarchy in .npmrc

npm reads configurations according to the following priority levels (from highest to lowest):

1. Command line arguments (–registry=url)
2. Project-level configuration (.npmrc in the project root directory)
3. User-level configuration (~/.npmrc)
4. Global configuration ($PREFIX/etc/npmrc)
5. Built-in npm configuration

Common Use Cases

1. Configuring npm Registry Mirrors

When the default npm registry is slow or unavailable, you can configure alternative mirrors through .npmrc:

registry=https://registry.npmjs.org/

2. Private Repository Authentication

When using private npm repositories in enterprise environments, authentication is required:

@mycompany:registry=https://npm.mycompany.com/
//npm.mycompany.com/:_authToken=YOUR_AUTH_TOKEN

3. Setting Up Proxies

When access to npm registries requires going through a proxy:

proxy=http://proxy.company.com:8080
https-proxy=http://proxy.company.com:8080

4. Configuring Package Version Prefixes

Control the version prefix used when running npm install --save:

save-prefix=~

5. Locking Publication Settings

Prevent accidental publication to public registries:

registry=https://registry.mycompany.com/
always-auth=true

Real-World Examples

Example 1: Multi-Registry Project Configuration

For projects using both public and private packages:

# Use company repository for private packages
@company:registry=https://npm.company.com/
//npm.company.com/:_authToken=${NPM_TOKEN}

# Use npm mirror for other packages
registry=https://registry.npmjs.org/

# Always use exact versions
save-exact=true

Example 2: CI/CD Environment Configuration

For CI/CD pipelines, .npmrc is often configured to ensure build stability:

# Increase network timeouts
fetch-timeout=300000
fetch-retries=5

# Disable progress bars to reduce log noise
progress=false

# Use private registry with authentication
registry=https://npm.mycompany.com/
//npm.mycompany.com/:_authToken=${CI_NPM_TOKEN}

# Ensure strict dependency locking
package-lock=true

Example 3: Monorepo Workspace Configuration

In Monorepo projects using Workspaces functionality:

# Enable workspaces
workspaces=true

# Prevent accidental publishing of subpackages
access=restricted

# Use exact version numbers
save-exact=true