How do you configure npm using .npmrc files and what are the common configuration options?

npm provides a powerful configuration system that allows developers to customize npm behavior through .npmrc files and command-line options. Understanding npm configuration is crucial for optimizing development workflows and troubleshooting common issues.

.npmrc File

Configuration File Locations

npm configuration files can exist in multiple locations, in order of priority from high to low:

1. Project-level: Project Root/.npmrc
2. User-level: ~/.npmrc
3. Global-level: $PREFIX/etc/npmrc
4. Built-in: npm built-in default configuration

Project-level Configuration

Create .npmrc file in the project root directory:

ini
# Project-level .npmrc
registry=https://registry.npmmirror.com
save-exact=true
engine-strict=true

Advantages:

• Project-specific configuration
• Can be committed to version control
• Shared among team members

User-level Configuration

.npmrc file located in the user's home directory:

bash
# View user-level configuration file location
npm config get userconfig

Common Configuration:

ini
# User-level .npmrc
registry=https://registry.npmmirror.com
prefix=/usr/local
cache=/Users/username/.npm-cache

Global-level Configuration

Configuration file located in the npm installation directory:

bash
# View global configuration file location
npm config get globalconfig

Common Configuration Options

Registry Configuration

ini
# Set registry
registry=https://registry.npmjs.org

# Use Taobao mirror
registry=https://registry.npmmirror.com

# Use private registry
registry=https://registry.yourcompany.com

# Set registry for specific scope
@yourcompany:registry=https://registry.yourcompany.com

Authentication Configuration

ini
# Use token authentication
//registry.npmjs.org/:_authToken=YOUR_TOKEN

# Use username and password
//registry.yourcompany.com/:username=your-username
//registry.yourcompany.com/:_password=YOUR_PASSWORD

# Read from environment variable
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Cache Configuration

ini
# Set cache directory
cache=/path/to/cache

# Set cache maximum size (bytes)
cache-max=10737418240

# Set cache minimum retention time (seconds)
cache-min=3600

Installation Configuration

ini
# Install exact versions
save-exact=true

# Save prefix
save-prefix=^

# Save dev dependencies
save-dev=false

# Save optional dependencies
save-optional=false

# Save peer dependencies
save-peer=false

# Use strict mode
engine-strict=true

# Ignore scripts
ignore-scripts=false

Network Configuration

ini
# Set proxy
https-proxy=http://proxy.example.com:8080
http-proxy=http://proxy.example.com:8080

# Set timeout (milliseconds)
fetch-timeout=60000

# Set retry count
fetch-retries=3

# Set retry minimum timeout (milliseconds)
fetch-retry-mintimeout=10000

# Set retry maximum timeout (milliseconds)
fetch-retry-maxtimeout=60000

# Set maximum concurrent connections
maxsockets=50

# Set network request concurrency
network-concurrency=16

Security Configuration

ini
# Enable strict SSL
strict-ssl=true

# Enable audit
audit=true

# Set audit level
audit-level=moderate

# Set CA certificate
cafile=/path/to/ca.pem

# Set certificate
cert=/path/to/cert.pem
key=/path/to/key.pem

Workspace Configuration

ini
# Enable workspaces
workspaces=true

# Set workspace directory
workspace=/path/to/workspace

Other Configuration

ini
# Set prefix
prefix=/usr/local

# Set log level
loglevel=info

# Set color output
color=true

# Set progress bar
progress=true

# Set Unicode characters
unicode=true

# Set shell
shell=bash

# Set editor
editor=vim

# Set browser
browser=google-chrome

Command-line Configuration

View Configuration

bash
# View all configuration
npm config list

# View specific configuration
npm config get registry

# View user configuration
npm config list --user

# View global configuration
npm config list --global

# View project configuration
npm config list --project

Set Configuration

bash
# Set configuration
npm config set registry https://registry.npmmirror.com

# Set global configuration
npm config set registry https://registry.npmmirror.com --global

# Delete configuration
npm config delete registry

# Edit configuration file
npm config edit

Environment Variables

npm supports configuration through environment variables:

bash
# Set registry
export npm_config_registry=https://registry.npmmirror.com

# Set cache directory
export npm_config_cache=/path/to/cache

# Set proxy
export npm_config_https-proxy=http://proxy.example.com:8080

# Set token
export npm_config__authToken=YOUR_TOKEN

Advanced Configuration

Scope Configuration

Set different configurations for different scopes:

ini
# Public packages use official registry
registry=https://registry.npmjs.org

# Private packages use private registry
@yourcompany:registry=https://registry.yourcompany.com

# Set authentication for specific scope
@yourcompany:registry=https://registry.yourcompany.com
//registry.yourcompany.com/:_authToken=${YOURCOMPANY_TOKEN}

Conditional Configuration

Select different configurations based on conditions:

ini
# Development environment
$npm_config_env=development
registry=https://registry.npmmirror.com

# Production environment
$npm_config_env=production
registry=https://registry.npmjs.org

Script Configuration

Use configuration in npm scripts:

json
{
  "scripts": {
    "install:dev": "npm install --registry=https://registry.npmmirror.com",
    "install:prod": "npm install --registry=https://registry.npmjs.org"
  }
}

Configuration Priority

Configuration priority from high to low:

1. Command-line options
2. Environment variables
3. Project-level .npmrc
4. User-level .npmrc
5. Global-level npmrc
6. npm built-in default configuration

Example:

bash
# Command-line options have highest priority
npm install --registry=https://custom-registry.com

# Even if .npmrc sets a different registry
# Command-line options will override

Best Practices

1. Project-level Configuration

ini
# Project .npmrc
registry=https://registry.npmmirror.com
save-exact=true
engine-strict=true
audit=true
audit-level=moderate

2. User-level Configuration

ini
# User .npmrc
registry=https://registry.npmmirror.com
cache=~/.npm-cache
prefix=~/.npm-global
loglevel=warn

3. CI/CD Configuration

yaml
# GitHub Actions
- name: Configure npm
  run: |
    echo "registry=https://registry.npmjs.org" > .npmrc
    echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" >> .npmrc
  env:
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

4. Security Configuration

ini
# Security configuration
strict-ssl=true
audit=true
audit-level=high
ignore-scripts=false

5. Performance Configuration

ini
# Performance configuration
cache=~/.npm-cache
cache-max=10737418240
maxsockets=50
network-concurrency=16
fetch-retries=3

Common Issues

1. Configuration Not Taking Effect

bash
# Check configuration priority
npm config list

# Check specific configuration
npm config get registry

# Clear cache
npm cache clean --force

2. Authentication Failure

bash
# Check token
npm config get _authToken

# Re-login
npm login

# Check registry
npm config get registry

3. Network Issues

bash
# Check proxy configuration
npm config get https-proxy

# Check timeout settings
npm config get fetch-timeout

# Use mirror
npm config set registry https://registry.npmmirror.com

4. Cache Issues

bash
# Clear cache
npm cache clean --force

# Verify cache
npm cache verify

# Check cache location
npm config get cache

Configuration Examples

Development Environment

ini
# Development environment .npmrc
registry=https://registry.npmmirror.com
save-exact=false
save-prefix=^
engine-strict=false
audit=false
loglevel=info

Production Environment

ini
# Production environment .npmrc
registry=https://registry.npmjs.org
save-exact=true
engine-strict=true
audit=true
audit-level=high
strict-ssl=true
loglevel=warn

Enterprise Environment

ini
# Enterprise environment .npmrc
registry=https://registry.yourcompany.com
@yourcompany:registry=https://registry.yourcompany.com
//registry.yourcompany.com/:_authToken=${NPM_TOKEN}
strict-ssl=true
audit=true
audit-level=moderate

Understanding the npm configuration system helps developers optimize development workflows, troubleshoot common issues, and ensure consistent configuration across the team.