> ## 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.

# .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

```ini theme={null}
# ./npmrc
registry=https://registry.npmjs.org/
```

### Per-user

```ini theme={null}
# ~/.npmrc
@myorg:registry=https://registry.company.com/
```

### Global

```ini theme={null}
# /etc/npmrc (Linux/macOS)
registry=https://registry.npmjs.org/
```

## Syntax

### Comments

```ini theme={null}
# This is a comment
; This is also a comment
```

### Key-value pairs

```ini theme={null}
registry=https://registry.npmjs.org/
loglevel=warn
```

### Scoped settings

```ini theme={null}
@myorg:registry=https://registry.company.com/
```

### Auth tokens

```ini theme={null}
//registry.npmjs.org/:_authToken=npm_...
```

## Common settings

### Registry

Set default registry:

```ini theme={null}
registry=https://registry.npmjs.org/
```

### Scoped registries

```ini theme={null}
@myorg:registry=https://registry.company.com/
@myteam:registry=https://npm.pkg.github.com/
```

### Authentication

Token auth:

```ini theme={null}
//registry.company.com/:_authToken=your-token-here
```

Basic auth:

```ini theme={null}
//registry.company.com/:username=myuser
//registry.company.com/:_password=base64-password
//registry.company.com/:email=user@example.com
```

### SSL/TLS

Strict SSL:

```ini theme={null}
strict-ssl=true
```

Custom CA certificate:

```ini theme={null}
cafile=/path/to/ca-cert.pem
```

### Proxy

HTTP proxy:

```ini theme={null}
proxy=http://proxy.company.com:8080
https-proxy=http://proxy.company.com:8080
```

No proxy for specific hosts:

```ini theme={null}
noproxy=localhost,127.0.0.1,.company.com
```

### Package settings

Save prefix:

```ini theme={null}
save-prefix=^
```

Save exact:

```ini theme={null}
save-exact=true
```

## Supported settings

Bun supports these `.npmrc` settings:

### Registry settings

```ini theme={null}
registry=https://registry.npmjs.org/
@scope:registry=https://registry.company.com/
```

### Authentication

```ini theme={null}
//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

```ini theme={null}
strict-ssl=true
cafile=/path/to/ca.pem
cert=/path/to/cert.pem
key=/path/to/key.pem
```

### Proxy

```ini theme={null}
proxy=http://proxy:8080
https-proxy=http://proxy:8080
noproxy=localhost,127.0.0.1
```

### Lockfile

```ini theme={null}
package-lock=true
```

### Install options

```ini theme={null}
production=false
optional=true
```

## Environment variables

Reference environment variables:

```ini theme={null}
//registry.company.com/:_authToken=${NPM_TOKEN}
registry=https://${REGISTRY_HOST}/
```

Set variables:

```bash theme={null}
export NPM_TOKEN=your-token
export REGISTRY_HOST=registry.company.com
bun install
```

## Examples

### GitHub Packages

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

Usage:

```bash theme={null}
export GITHUB_TOKEN=ghp_...
bun add @myorg/package
```

### GitLab Packages

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

### Private registry with basic auth

```ini theme={null}
# ./npmrc
registry=https://registry.company.com/
//registry.company.com/:username=myuser
//registry.company.com/:_password=bXlwYXNzd29yZA==
always-auth=true
```

Encode password:

```bash theme={null}
echo -n "mypassword" | base64
```

### Corporate proxy

```ini theme={null}
# ~/.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

```ini theme={null}
# ./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:

```ini theme={null}
# Good
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

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

Add to `.gitignore`:

```gitignore theme={null}
.npmrc
```

### Per-project tokens

For projects requiring auth:

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

```gitignore theme={null}
# .gitignore
# Don't commit if .npmrc contains actual tokens
```

### CI/CD

Generate `.npmrc` in CI:

```yaml theme={null}
# 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

```bash theme={null}
# Test registry connection
curl https://registry.npmjs.org/react

# Check auth
bun pm whoami
```

### Clear auth cache

Delete cached credentials:

```bash theme={null}
rm ~/.npmrc
```

Or remove specific tokens:

```bash theme={null}
vim ~/.npmrc
# Remove _authToken lines
```

### Test .npmrc settings

Create test `.npmrc`:

```ini theme={null}
registry=https://registry.npmjs.org/
loglevel=verbose
```

Install:

```bash theme={null}
bun install --verbose
```

### Permission errors

Fix `.npmrc` permissions:

```bash theme={null}
chmod 600 ~/.npmrc
```

## Migration

### From npm

Existing `.npmrc` works with Bun:

```bash theme={null}
# Your existing .npmrc
cat ~/.npmrc

# Works with Bun
bun install
```

### From Yarn

Yarn's `.yarnrc` is different. Convert to `.npmrc`:

```yaml theme={null}
# .yarnrc (Yarn)
registry "https://registry.company.com/"
```

To:

```ini theme={null}
# .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)

```ini theme={null}
registry=https://registry.npmjs.org/
```

### bunfig.toml (Bun-specific)

```toml theme={null}
[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

```ini theme={null}
# .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:

```bash theme={null}
cat .npmrc.local >> .npmrc
```

### Document required setup

```markdown theme={null}
# 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

```ini theme={null}
# Flexible
//registry.company.com/:_authToken=${NPM_TOKEN}

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

### Validate .npmrc

Check syntax:

```bash theme={null}
# Ensure no empty lines between key-value pairs
grep -v '^#' .npmrc | grep -v '^;' | grep -v '^$'
```

### Keep it minimal

```ini theme={null}
# 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/
```