npmrc

Key Takeaways

• `.npmrc` is the primary configuration file for npm, governing package installation, publishing, and registry behavior.
• It supports three scopes—global, user, and project—each overriding the previous in a predictable order.
• Common settings include registry, proxy, strict-ssl, and cache, but advanced options like auth tokens and package-lock flags offer fine‑tuned control.
• Comparing npmrc with Yarn’s .yarnrc or pnpm’s pnpmfile.cjs highlights similarities in overriding behavior and differences in syntax and feature sets.
• Best practices: keep sensitive data in environment variables, use --global flags sparingly, and document all custom npmrc entries in project readmes.

What Is a .npmrc File?

The .npmrc file is npm’s configuration layer, parsed at runtime to determine how npm behaves. It can exist at three levels:

• Global (npm config -g): Applies to all users on the system.
• User (~/.npmrc): Applies to the current user across all projects.
• Project (./.npmrc): Overrides both global and user settings for a specific repository.

Each level follows an inheritance chain where project settings take precedence over user, which in turn overrides global defaults.

Configuring npmrc: Scope and Syntax

Global vs User vs Project

Typical use cases:

Scope	Common Use	Example Path
Global	Set a default registry for all users on a CI server.	/etc/npmrc
User	Store authentication tokens for a developer’s personal machine.	~/.npmrc
Project	Pin to a private registry for a specific repository.	./.npmrc

Syntax Overview

Each line follows a key=value format. Comments start with # or ;. Lines can be continued with a backslash (\) for multiline values.

Common npmrc Settings

Setting	Description	Example
registry	The base URL where npm looks for packages.	registry=https://registry.npmjs.org/
proxy	HTTP proxy for outbound requests.	proxy=http://proxy.company.com:8080/
strict-ssl	Require SSL certificates to be valid.	strict-ssl=true
cache	Custom cache directory path.	cache=/var/npm-cache
package-lock	Generate or ignore package-lock.json during install.	package-lock=false
save-exact	Pin installed versions to exact numbers in package.json.	save-exact=true
//registry.npmjs.org/:_authToken	Auth token for accessing private scopes.	//registry.npmjs.org/:_authToken=xxxxxxxxxxxxxxxx

Advanced Configurations

Proxies and Authentication

When working behind corporate firewalls, you might need both proxy and https-proxy defined. For secure authentication, it is recommended to store tokens in environment variables and reference them via ${NPM_TOKEN} in the .npmrc file.

Conditional Registries

Using @scope:registry syntax allows per‑scope registry overrides. Example:

@myorg:registry=https://npm.myorg.com/

Comparing npmrc to Other Configuration Systems

Feature	npmrc (npm)	.yarnrc (Yarn)	pnpmfile.cjs (pnpm)
Syntax	Key=Value (INI style)	Key: Value (YAML style)	JavaScript module exporting hooks
Scope Hierarchy	Global > User > Project	Global > User > Project (similar)	Global > Project (no user scope)
Registry Overrides	Per‑scope via @scope:registry	Per‑scope via registry field in package.json	Per‑scope via packages config in pnpm-workspace.yaml
Auth Token Storage	Inline token string or environment variable	Inline token string or authToken setting	Inline token or authHeader in pnpmfile.cjs
Extensibility	No plugin system in config	Plugins via plugins field	Hooks via pnpmfile.cjs

Checklist for npmrc Best Practices

• Document all custom settings in the repository’s README.md for onboarding.
• Avoid hard‑coding authentication tokens; use environment variables or npm login instead.
<