Skip to main content
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:[email protected]/"
Warning: Avoid committing credentials. Use environment variables: 
[install]
registry = "https://${NPM_USER}:${NPM_PASSWORD}@registry.company.com/"

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us