.npmrc File for Node.js and Bun
Comprehensive guide to .npmrc - configuring registry, authentication, and installation for Node.js and Bun
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]
.npmrcacts as a configuration file for your package manager, similar to how.envworks 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:
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
.npmrcandbunfig.toml, ensure they don’t configure the same thing in conflicting ways.
Practical Examples#
Basic Configuration#
# Use default registry
registry=https://registry.npmjs.org
# Always save exact version numbers (no ^ or ~ prefix)
save-exact=trueiniConfiguration with Private Registry#
# 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.orginiConfiguration for GitHub Packages#
# GitHub Packages registry
@your-org:registry=https://npm.pkg.github.com
# GitHub token for authentication
//npm.pkg.github.com:_authToken=${GITHUB_TOKEN}iniConfiguration for GitLab Package Registry#
# 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}iniUsing 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 configbashWhy 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:
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}yaml# Token will be replaced from environment variable
//npm.mycompany.com:_authToken=${NPM_TOKEN}iniViewing Active Configuration#
To see which .npmrc file is being used:
# With npm
npm config list
# With Bun
bun pm configbashPractical Tips#
- Always use project-level
.npmrcfor project-specific configuration - Never commit tokens to git - use environment variables instead
- Use scoped registries for your company’s private packages
- Check your configuration when facing authentication errors
- 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.