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

[install]
registry = "https://registry.company.com/"

Via environment variable

export BUN_CONFIG_REGISTRY="https://registry.company.com/"
bun install

Via .npmrc

Bun respects .npmrc files:

# .npmrc
registry=https://registry.company.com/

Scoped registries

Use different registries for scoped packages:

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

Or in .npmrc:

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

Now packages are resolved from scoped registries:

# 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

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

Via .npmrc

@myorg:registry=https://registry.company.com/
//registry.company.com/:_authToken=your-auth-token

Basic authentication

# .npmrc
registry=https://registry.company.com/
//registry.company.com/:username=myuser
//registry.company.com/:_password=base64-encoded-password

Encode password:

echo -n "mypassword" | base64

URL with credentials

[install]
registry = "https://username:[e-mail]/"

Warning: Avoid committing credentials. Use environment variables:

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

Popular registries

npm (default)

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

GitHub Packages

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

Or .npmrc:

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

GitLab Packages

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

Or .npmrc:

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

Azure Artifacts

# .npmrc
registry=https://pkgs.dev.azure.com/myorg/_packaging/myfeed/npm/registry/
always-auth=true

Authenticate with:

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

JFrog Artifactory

[install]
registry = "https://mycompany.jfrog.io/artifactory/api/npm/npm-local/"

Verdaccio (private registry)

[install]
registry = "http://localhost:4873/"

Nexus Repository

[install]
registry = "https://nexus.company.com/repository/npm-group/"

Environment-specific registries

Development vs Production

# bunfig.dev.toml (development)
[install]
registry = "http://localhost:4873/"

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

Use with:

# Development
bun install --config bunfig.dev.toml

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

Registry mirrors

Use faster mirrors:

# 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

# ./npmrc
registry=https://registry.company.com/

Per-user

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

Global

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

Troubleshooting

Test registry connection

curl https://registry.npmjs.org/react

Should return package metadata.

Verify authentication

# Test with npm (uses same .npmrc)
npm whoami

Or:

bun pm whoami

Clear registry cache

bun pm cache rm

Debug registry requests

BUN_DEBUG_QUIET_LOGS=0 bun install --verbose

Certificate errors

For self-signed certificates:

# .npmrc
strict-ssl=false

Warning: Only use in development.

Or provide CA certificate:

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

Proxy configuration

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

Or:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
bun install

CI/CD

GitHub Actions

- 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

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

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:

# Use buildkit secrets
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    bun install --frozen-lockfile

Build:

docker build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

Best practices

Don’t commit tokens

Use environment variables:

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

Add .npmrc to .gitignore if it contains secrets:

.npmrc

Use scoped registries

Scope private packages:

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

Public packages use default registry.

Verify package integrity

Bun verifies package checksums automatically. For additional security:

[install]
verify = true

Use HTTPS

Always use HTTPS registries:

[install]
registry = "https://registry.company.com/"  # Good
# registry = "http://registry.company.com/"  # Bad

Examples

Private GitHub packages

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

export GITHUB_TOKEN=ghp_...
bun install

Multiple registries

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

Local development registry

# Start Verdaccio
verbatim verdaccio

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