Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
Use this file to discover all available pages before exploring further.
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):
- Built-in defaults
- Global config -
/etc/npmrc (Linux/macOS)
- User config -
~/.npmrc
- 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
# 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
//registry.company.com/:username=myuser
//registry.company.com/:_password=base64-password
//registry.company.com/:email=user@example.com
SSL/TLS
Strict SSL:
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
noproxy=localhost,127.0.0.1,.company.com
Package settings
Save prefix:
Save exact:
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=user@example.com
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
Install options
production=false
optional=true
Environment variables
Reference environment variables:
//registry.company.com/:_authToken=${NPM_TOKEN}
registry=https://${REGISTRY_HOST}/
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}
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
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...
.gitignore:
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:
/etc/npmrc~/.npmrc./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:
Or remove specific tokens:
vim ~/.npmrc
# Remove _authToken lines
Test .npmrc settings
Create test .npmrc:
registry=https://registry.npmjs.org/
loglevel=verbose
Permission errors
Fix .npmrc permissions:
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/"
# .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...
cat .npmrc.local >> .npmrc
Document required setup
# README.md
## Setup
1. Copy `.npmrc.example` to `.npmrc`
2. Add your auth token:
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/
