Package Manager Advanced Configuration

.npmrc support

Package Manager npmrc configuration

Package Manager npmrc configuration

Bun loads configuration options from .npmrc files, so you can reuse your existing registry and scope configuration.

We recommend migrating your .npmrc file to Bun's bunfig.toml format, which supports more options, including Bun-specific ones.

Supported options

Set the default registry

Bun resolves packages from the default registry, which is npm's official registry (https://registry.npmjs.org/).

To change it, set the registry option in .npmrc:

.npmrc

registry=http://localhost:4873/

The equivalent bunfig.toml option is install.registry:

bunfig.toml

install.registry = "http://localhost:4873/"

Set the registry for a specific scope

@<scope>:registry sets the registry for a specific scope:

.npmrc

@myorg:registry=http://localhost:4873/

The equivalent bunfig.toml option is to add a key in install.scopes:

bunfig.toml

[install.scopes]
myorg = "http://localhost:4873/"

Configure options for a specific registry

//<registry_url>/:<key>=<value> sets options for a specific registry:

.npmrc

# set an auth token for the registry
# ${...} is a placeholder for environment variables
//http://localhost:4873/:_authToken=${NPM_TOKEN}

# or you could set a username and password
# note that the password is base64 encoded
//http://localhost:4873/:username=myusername

//http://localhost:4873/:_password=${NPM_PASSWORD}

# or use _auth, which is your username and password
# combined into a single string, which is then base 64 encoded
//http://localhost:4873/:_auth=${NPM_AUTH}

The following options are supported:

_authToken
username
_password (base64 encoded password)
_auth (base64 encoded username:password, for example btoa(username + ":" + password))
email

The equivalent bunfig.toml option is to add a key in install.scopes:

bunfig.toml

[install.scopes]
myorg = { url = "http://localhost:4873/", username = "myusername", password = "$NPM_PASSWORD" }

`link-workspace-packages`: Control workspace package installation

Controls how workspace packages are installed when available locally:

.npmrc

link-workspace-packages=true

The equivalent bunfig.toml option is install.linkWorkspacePackages:

bunfig.toml

[install]
linkWorkspacePackages = true

`save-exact`: Save exact versions

Always saves exact versions without the ^ prefix:

.npmrc

save-exact=true

The equivalent bunfig.toml option is install.exact:

bunfig.toml

[install]
exact = true

`ignore-scripts`: Skip lifecycle scripts

Prevents running lifecycle scripts during installation:

.npmrc

ignore-scripts=true

This is equivalent to using the --ignore-scripts flag with bun install.

`dry-run`: Preview changes without installing

Shows what would be installed without installing anything:

.npmrc

dry-run=true

The equivalent bunfig.toml option is install.dryRun:

bunfig.toml

[install]
dryRun = true

`cache`: Configure cache directory

Set the cache directory path, or disable caching:

.npmrc

# set a custom cache directory
cache=/path/to/cache

# or disable caching
cache=false

The equivalent bunfig.toml option is install.cache:

bunfig.toml

[install.cache]
# set a custom cache directory
dir = "/path/to/cache"

# or disable caching
disable = true

`ca` and `cafile`: Configure CA certificates

Configure custom CA certificates for registry connections:

.npmrc

# single CA certificate
ca="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# multiple CA certificates
ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# or specify a path to a CA file
cafile=/path/to/ca-bundle.crt

`omit` and `include`: Control dependency types

Control which dependency types are installed:

.npmrc

# omit dev dependencies
omit=dev

# omit multiple types
omit[]=dev
omit[]=optional

# include specific types (overrides omit)
include=dev

Valid values: dev, peer, optional

`install-strategy` and `node-linker`: Installation strategy

Control how packages are laid out in node_modules. For compatibility with other package managers, Bun accepts both npm's install-strategy and pnpm/yarn's node-linker. See isolated installs for how the hoisted and isolated layouts differ.

npm's install-strategy:

.npmrc

# flat node_modules structure (default)
install-strategy=hoisted

# symlinked structure
install-strategy=linked

pnpm/yarn's node-linker:

node-linker controls the installation mode. Bun accepts values from both pnpm and yarn:

Value	Description	Accepted by
`isolated`	Symlinked structure with isolated dependencies	pnpm
`hoisted`	Flat node_modules structure	pnpm
`pnpm`	Symlinked structure (same as `isolated`)	yarn
`node-modules`	Flat node_modules structure (same as `hoisted`)	yarn

.npmrc

# symlinked/isolated mode
node-linker=isolated
node-linker=pnpm

# flat/hoisted mode
node-linker=hoisted
node-linker=node-modules

`public-hoist-pattern` and `hoist-pattern`: Control hoisting

Control which packages are hoisted to the root node_modules:

.npmrc

# packages matching this pattern will be hoisted to the root
public-hoist-pattern=*eslint*

# multiple patterns
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# control general hoisting behavior
hoist-pattern=*

# isolated linker only: disable the node_modules/.bun/node_modules fallback,
# so store packages only resolve declared deps (plus the root node_modules).
# Hoisted installs ignore this setting.
hoist=false

Security Scanner API

Previous Page

On this page

Supported options

Set the default registry

Set the registry for a specific scope

Configure options for a specific registry

link-workspace-packages: Control workspace package installation

save-exact: Save exact versions

ignore-scripts: Skip lifecycle scripts

dry-run: Preview changes without installing

cache: Configure cache directory

ca and cafile: Configure CA certificates

omit and include: Control dependency types

install-strategy and node-linker: Installation strategy

public-hoist-pattern and hoist-pattern: Control hoisting