blog.dopana

Back

Have you ever wondered why some projects have a .npmrc file in their root directory? Or how to configure a private registry for your company? The .npmrc file is the key to controlling how package managers like npm, pnpm, yarn, and Bun behave.

In this post, we’ll explore how .npmrc works, especially when using Bun - a new ultra-fast package manager.

Why .npmrc Matters#

Imagine you’re working on a project that uses private packages from your company. If you had to enter your username and password every time you run npm install or bun install, that would be incredibly frustrating. .npmrc solves this by storing configuration centrally.

[!NOTE] .npmrc acts as a configuration file for your package manager, similar to how .env works for environment variables but specifically for npm/Bun.

What is .npmrc?#

.npmrc is a key-value configuration file used to set options for package managers (npm, pnpm, yarn, Bun). It can contain:

  • Registry URLs (where to download packages from)
  • Authentication tokens (to access private registries)
  • Installation settings like save-exact, engine-strict, etc.

.npmrc Priority Order#

Package managers look for .npmrc files in multiple locations, ordered from lowest to highest priority:

Default npmGlobal/etc/npmrcUser~/.npmrcProject./.npmrcCLI/EnvironmentNPM_CONFIG_REGISTRY

This means:

  • Default: Built-in npm defaults
  • Global: System-wide file (usually /etc/npmrc)
  • User: Per-user file in your home directory (~/.npmrc)
  • Project: Local file in your project root (./.npmrc) - where you should configure project-specific settings
  • CLI/Environment: Command-line flags or environment variables (highest priority)

[!TIP] If the same configuration appears in multiple locations, the one with higher priority overrides the lower priority one.

How Bun Handles .npmrc#

One of Bun’s strengths is its full compatibility with standard .npmrc files. You can drop Bun into an existing Node.js project without changing your registry or authentication setup.

Settings Supported by Bun#

Bun supports common .npmrc directives including:

  • Registry URLs: Configure default registry and scoped registries
  • Scoped registries: Assign a specific registry to a scope (e.g., @mycompany)
  • Authentication tokens: _authToken, _auth, username, _password, email
  • Project options: save-exact=true, link-workspace-packages

Bunfig.toml - Bun’s Native Alternative#

Bun also has its own native configuration file called bunfig.toml, but it continues to respect .npmrc for cross-tool compatibility.

[!WARNING] If you use both .npmrc and bunfig.toml, ensure they don’t configure the same thing in conflicting ways.

Practical Examples#

Basic Configuration#

.npmrc
# Use default registry
registry=https://registry.npmjs.org

# Always save exact version numbers (no ^ or ~ prefix)
save-exact=true
ini

Configuration with Private Registry#

.npmrc
# Configure registry for company scope
@mycompany:registry=https://npm.mycompany.com

# Authentication token for company registry
//npm.mycompany.com:_authToken=${NPM_TOKEN}

# Default registry for other packages
registry=https://registry.npmjs.org
ini

Configuration for GitHub Packages#

.npmrc
# GitHub Packages registry
@your-org:registry=https://npm.pkg.github.com

# GitHub token for authentication
//npm.pkg.github.com:_authToken=${GITHUB_TOKEN}
ini

Configuration for GitLab Package Registry#

.npmrc
# GitLab Package Registry
@your-group:registry=https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/

# GitLab token
//gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/:_authToken=${GITLAB_TOKEN}
ini

Using with Bun#

When you have a .npmrc file in your project, Bun automatically reads it when running bun install:

# Bun will read .npmrc and apply configuration
bun install

# View current Bun configuration
bun pm config
bash

Why Use save-exact=true?#

When save-exact=true is enabled, the package manager saves the exact version in package.json instead of using ranges (like ^1.2.3 or ~1.2.3).

Pros:

  • Ensures everyone on the team installs the same version
  • Avoids breakage when a package releases an incompatible update
  • Predictable dependencies in production

Cons:

  • Must manually update dependencies
  • Don’t automatically get patch updates

Configuration in CI/CD#

In CI/CD environments, you typically use environment variables instead of committing tokens to the file:

.github/workflows/ci.yml
env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
yaml
.npmrc
# Token will be replaced from environment variable
//npm.mycompany.com:_authToken=${NPM_TOKEN}
ini

Viewing Active Configuration#

To see which .npmrc file is being used:

# With npm
npm config list

# With Bun
bun pm config
bash

Practical Tips#

  1. Always use project-level .npmrc for project-specific configuration
  2. Never commit tokens to git - use environment variables instead
  3. Use scoped registries for your company’s private packages
  4. Check your configuration when facing authentication errors
  5. Read the documentation for your private registry (GitHub, GitLab, Azure Artifacts)

Conclusion#

.npmrc is an essential tool for managing how your package manager behaves in your project. With Bun’s support, you can continue using this file without changing configuration when switching from npm to Bun.

Understanding the priority order and how to configure it will help you avoid many authentication and dependency management issues in the future.

References#