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

# Registries

Configure npm registries for package installation.

## Default registry

Bun uses npm's public registry by default:

```
https://registry.npmjs.org/
```

## Custom registry

### Global registry

Set a custom registry for all packages:

#### Via bunfig.toml

```toml theme={null}
[install]
registry = "https://registry.company.com/"
```

#### Via environment variable

```bash theme={null}
export BUN_CONFIG_REGISTRY="https://registry.company.com/"
bun install
```

#### Via .npmrc

Bun respects `.npmrc` files:

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

### Scoped registries

Use different registries for scoped packages:

```toml theme={null}
[install.scopes]
"@myorg" = { registry = "https://registry.company.com/" }
"@myteam" = { registry = "https://npm.pkg.github.com/" }
```

Or in `.npmrc`:

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

Now packages are resolved from scoped registries:

```bash theme={null}
# From https://registry.company.com/
bun add @myorg/package

# From https://npm.pkg.github.com/
bun add @myteam/utils

# From default registry (https://registry.npmjs.org/)
bun add react
```

## Authentication

### Token authentication

#### Via bunfig.toml

```toml theme={null}
[install.scopes]
"@myorg" = { 
  registry = "https://registry.company.com/",
  token = "your-auth-token"
}
```

#### Via .npmrc

```ini theme={null}
@myorg:registry=https://registry.company.com/
//registry.company.com/:_authToken=your-auth-token
```

### Basic authentication

```ini theme={null}
# .npmrc
registry=https://registry.company.com/
//registry.company.com/:username=myuser
//registry.company.com/:_password=base64-encoded-password
```

Encode password:

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

### URL with credentials

```toml theme={null}
[install]
registry = "https://username:password@registry.company.com/"
```

**Warning:** Avoid committing credentials. Use environment variables:

```toml theme={null}
[install]
registry = "https://${NPM_USER}:${NPM_PASSWORD}@registry.company.com/"
```

## Popular registries

### npm (default)

```toml theme={null}
[install]
registry = "https://registry.npmjs.org/"
```

### GitHub Packages

```toml theme={null}
[install.scopes]
"@myorg" = {
  registry = "https://npm.pkg.github.com/",
  token = "ghp_..."
}
```

Or `.npmrc`:

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

### GitLab Packages

```toml theme={null}
[install.scopes]
"@mygroup" = {
  registry = "https://gitlab.com/api/v4/packages/npm/",
  token = "glpat-..."
}
```

Or `.npmrc`:

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

### Azure Artifacts

```ini theme={null}
# .npmrc
registry=https://pkgs.dev.azure.com/myorg/_packaging/myfeed/npm/registry/
always-auth=true
```

Authenticate with:

```bash theme={null}
# Generate token in Azure DevOps
# Then add to .npmrc:
//pkgs.dev.azure.com/myorg/_packaging/myfeed/npm/registry/:_authToken=YOUR_TOKEN
```

### JFrog Artifactory

```toml theme={null}
[install]
registry = "https://mycompany.jfrog.io/artifactory/api/npm/npm-local/"
```

### Verdaccio (private registry)

```toml theme={null}
[install]
registry = "http://localhost:4873/"
```

### Nexus Repository

```toml theme={null}
[install]
registry = "https://nexus.company.com/repository/npm-group/"
```

## Environment-specific registries

### Development vs Production

```toml theme={null}
# bunfig.dev.toml (development)
[install]
registry = "http://localhost:4873/"

# bunfig.prod.toml (production)
[install]
registry = "https://registry.npmjs.org/"
```

Use with:

```bash theme={null}
# Development
bun install --config bunfig.dev.toml

# Production
bun install --config bunfig.prod.toml
```

## Registry mirrors

Use faster mirrors:

```toml theme={null}
# China mirror (npmmirror)
[install]
registry = "https://registry.npmmirror.com/"

# Europe mirror
[install]
registry = "https://registry.npmjs.eu/"
```

## .npmrc locations

Bun reads `.npmrc` in this order:

1. **Project** - `./`
2. **User** - `~/.npmrc`
3. **Global** - `/etc/npmrc`

### Per-project

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

### Per-user

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

### Global

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

## Troubleshooting

### Test registry connection

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

Should return package metadata.

### Verify authentication

```bash theme={null}
# Test with npm (uses same .npmrc)
npm whoami
```

Or:

```bash theme={null}
bun pm whoami
```

### Clear registry cache

```bash theme={null}
bun pm cache rm
```

### Debug registry requests

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

### Certificate errors

For self-signed certificates:

```ini theme={null}
# .npmrc
strict-ssl=false
```

**Warning:** Only use in development.

Or provide CA certificate:

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

### Proxy configuration

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

Or:

```bash theme={null}
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
bun install
```

## CI/CD

### GitHub Actions

```yaml theme={null}
- name: Setup registry auth
  run: |
    echo "@myorg:registry=https://npm.pkg.github.com/" >> .npmrc
    echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> .npmrc

- name: Install dependencies
  run: bun install
```

### GitLab CI

```yaml theme={null}
variables:
  NPM_TOKEN: $CI_JOB_TOKEN

before_script:
  - echo "@mygroup:registry=https://gitlab.com/api/v4/packages/npm/" >> .npmrc
  - echo "//gitlab.com/api/v4/packages/npm/:_authToken=${NPM_TOKEN}" >> .npmrc
  - bun install
```

### Docker

```dockerfile theme={null}
FROM oven/bun:latest

WORKDIR /app

# Copy registry config
COPY .npmrc .

# Or set via environment
ENV BUN_CONFIG_REGISTRY=https://registry.company.com/

COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

COPY . .

CMD ["bun", "start"]
```

With secrets:

```dockerfile theme={null}
# Use buildkit secrets
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    bun install --frozen-lockfile
```

Build:

```bash theme={null}
docker build --secret id=npmrc,src=$HOME/.npmrc -t myapp .
```

## Best practices

### Don't commit tokens

Use environment variables:

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

Add `.npmrc` to `.gitignore` if it contains secrets:

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

### Use scoped registries

Scope private packages:

```toml theme={null}
[install.scopes]
"@mycompany" = { registry = "https://registry.company.com/" }
```

Public packages use default registry.

### Verify package integrity

Bun verifies package checksums automatically. For additional security:

```toml theme={null}
[install]
verify = true
```

### Use HTTPS

Always use HTTPS registries:

```toml theme={null}
[install]
registry = "https://registry.company.com/"  # Good
# registry = "http://registry.company.com/"  # Bad
```

## Examples

### Private GitHub packages

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

```bash theme={null}
export GITHUB_TOKEN=ghp_...
bun install
```

### Multiple registries

```toml theme={null}
[install.scopes]
"@company" = { registry = "https://registry.company.com/" }
"@opensource" = { registry = "https://registry.npmjs.org/" }
"@github" = { registry = "https://npm.pkg.github.com/" }
```

### Local development registry

```bash theme={null}
# Start Verdaccio
verbatim verdaccio

# Use local registry
echo 'registry=http://localhost:4873/' > .npmrc
bun install
```