.npmrc

Configure npm-compatible settings using .npmrc files.

What is .npmrc?

.npmrc is a configuration file for npm-compatible package managers. Bun reads and respects most .npmrc settings for compatibility with existing projects.

File locations

Bun reads .npmrc files in this order (later files override earlier ones):

1. Built-in defaults
2. Global config - /etc/npmrc (Linux/macOS)
3. User config - ~/.npmrc
4. Project config - ./npmrc (in project root)

Per-project

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

Per-user

# ~/.npmrc
@myorg:registry=https://registry.company.com/

Global

# /etc/npmrc (Linux/macOS)
registry=https://registry.npmjs.org/

Syntax

Comments

# This is a comment
; This is also a comment

Key-value pairs

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

Scoped settings

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

Auth tokens

//registry.npmjs.org/:_authToken=npm_...

Common settings

Registry

Set default registry:

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

Scoped registries

@myorg:registry=https://registry.company.com/
@myteam:registry=https://npm.pkg.github.com/

Authentication

Token auth:

//registry.company.com/:_authToken=your-token-here

Basic auth:

//registry.company.com/:username=myuser
//registry.company.com/:_password=base64-password
//registry.company.com/:email=[e-mail]

SSL/TLS

Strict SSL:

strict-ssl=true

Custom CA certificate:

cafile=/path/to/ca-cert.pem

Proxy

HTTP proxy:

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

No proxy for specific hosts:

noproxy=localhost,127.0.0.1,.company.com

Package settings

Save prefix:

save-prefix=^

Save exact:

save-exact=true

Supported settings

Bun supports these .npmrc settings:

Registry settings

registry=https://registry.npmjs.org/
@scope:registry=https://registry.company.com/

Authentication

//registry.npmjs.org/:_authToken=token
//registry.npmjs.org/:username=user
//registry.npmjs.org/:_password=pass
//registry.npmjs.org/:email=[e-mail]
always-auth=true

SSL/TLS

strict-ssl=true
cafile=/path/to/ca.pem
cert=/path/to/cert.pem
key=/path/to/key.pem

Proxy

proxy=http://proxy:8080
https-proxy=http://proxy:8080
noproxy=localhost,127.0.0.1

Lockfile

package-lock=true

Install options

production=false
optional=true

Environment variables

Reference environment variables:

//registry.company.com/:_authToken=${NPM_TOKEN}
registry=https://${REGISTRY_HOST}/

Set variables:

export NPM_TOKEN=your-token
export REGISTRY_HOST=registry.company.com
bun install

Examples

GitHub Packages

# ~/.npmrc
@myorg:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Usage:

export GITHUB_TOKEN=ghp_...
bun add @myorg/package

GitLab Packages

# ./npmrc
@mygroup:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}

Private registry with basic auth

# ./npmrc
registry=https://registry.company.com/
//registry.company.com/:username=myuser
//registry.company.com/:_password=bXlwYXNzd29yZA==
always-auth=true

Encode password:

echo -n "mypassword" | base64

Corporate proxy

# ~/.npmrc
proxy=http://proxy.company.com:8080
https-proxy=http://proxy.company.com:8080
noproxy=localhost,127.0.0.1,.company.com
strict-ssl=false

Multiple registries

# ./npmrc
# Default registry
registry=https://registry.npmjs.org/

# Company packages
@company:registry=https://registry.company.com/
//registry.company.com/:_authToken=${COMPANY_TOKEN}

# GitHub packages  
@github:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Security

Don’t commit tokens

Use environment variables:

# Good
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# Bad
//registry.npmjs.org/:_authToken=npm_abc123...

Add to .gitignore:

.npmrc

Per-project tokens

For projects requiring auth:

# .npmrc (committed)
@myorg:registry=https://registry.company.com/
//registry.company.com/:_authToken=${COMPANY_TOKEN}

# .gitignore
# Don't commit if .npmrc contains actual tokens

CI/CD

Generate .npmrc in CI:

# GitHub Actions
- name: Setup npmrc
  run: |
    echo "@myorg:registry=https://npm.pkg.github.com/" >> .npmrc
    echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> .npmrc

Troubleshooting

Check which .npmrc is used

Bun reads in this order:

1. /etc/npmrc
2. ~/.npmrc
3. ./npmrc

Later files override earlier ones.

Debug registry configuration

# Test registry connection
curl https://registry.npmjs.org/react

# Check auth
bun pm whoami

Clear auth cache

Delete cached credentials:

rm ~/.npmrc

Or remove specific tokens:

vim ~/.npmrc
# Remove _authToken lines

Test .npmrc settings

Create test .npmrc:

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

Install:

bun install --verbose

Permission errors

Fix .npmrc permissions:

chmod 600 ~/.npmrc

Migration

From npm

Existing .npmrc works with Bun:

# Your existing .npmrc
cat ~/.npmrc

# Works with Bun
bun install

From Yarn

Yarn’s .yarnrc is different. Convert to .npmrc:

# .yarnrc (Yarn)
registry "https://registry.company.com/"

To:

# .npmrc (Bun/npm)
registry=https://registry.company.com/

From pnpm

pnpm uses .npmrc - should work with Bun directly.

bunfig.toml vs .npmrc

Bun supports both:

.npmrc (npm-compatible)

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

bunfig.toml (Bun-specific)

[install]
registry = "https://registry.npmjs.org/"

Precedence

bunfig.toml overrides .npmrc.

When to use each

Use .npmrc for:

• Cross-tool compatibility (npm, Yarn, pnpm)
• Auth tokens
• Registry configuration

Use bunfig.toml for:

• Bun-specific settings
• Advanced configuration
• Better IDE support (TOML)

Best practices

Separate auth from config

# .npmrc (committed)
registry=https://registry.npmjs.org/
@myorg:registry=https://registry.company.com/

# .npmrc.local (not committed)
//registry.company.com/:_authToken=abc123...

Merge in CI:

cat .npmrc.local >> .npmrc

Document required setup

# README.md

## Setup

1. Copy `.npmrc.example` to `.npmrc`
2. Add your auth token:

//registry.company.com/:_authToken=YOUR_TOKEN

3. Run `bun install`

Use environment variables

# Flexible
//registry.company.com/:_authToken=${NPM_TOKEN}

# Different tokens per environment
//registry.company.com/:_authToken=${NPM_TOKEN_${ENV}}

Validate .npmrc

Check syntax:

# Ensure no empty lines between key-value pairs
grep -v '^#' .npmrc | grep -v '^;' | grep -v '^$'

Keep it minimal

# Bad: Too many settings
registry=https://registry.npmjs.org/
save-exact=true
engine-strict=true
package-lock=true
optional=true
...

# Good: Only what's needed
registry=https://registry.npmjs.org/
@myorg:registry=https://registry.company.com/