mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
246 lines
6.3 KiB
Plaintext
246 lines
6.3 KiB
Plaintext
---
|
|
title: .npmrc support
|
|
description:
|
|
---
|
|
|
|
Bun supports loading configuration options from [`.npmrc`](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc) files, allowing you to reuse existing registry/scope configurations.
|
|
|
|
<Note>
|
|
We recommend migrating your `.npmrc` file to Bun's [`bunfig.toml`](/runtime/bunfig) format, as it provides more
|
|
flexible options and can let you configure Bun-specific options.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Supported options
|
|
|
|
### Set the default registry
|
|
|
|
The default registry is used to resolve packages, its default value is `npm`'s official registry (`https://registry.npmjs.org/`).
|
|
|
|
To change it, you can set the `registry` option in `.npmrc`:
|
|
|
|
```ini .npmrc icon="npm"
|
|
registry=http://localhost:4873/
|
|
```
|
|
|
|
The equivalent `bunfig.toml` option is [`install.registry`](/runtime/bunfig#install-registry):
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
install.registry = "http://localhost:4873/"
|
|
```
|
|
|
|
### Set the registry for a specific scope
|
|
|
|
`@<scope>:registry` allows you to set the registry for a specific scope:
|
|
|
|
```ini .npmrc icon="npm"
|
|
@myorg:registry=http://localhost:4873/
|
|
```
|
|
|
|
The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](/runtime/bunfig#install-registry):
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
[install.scopes]
|
|
myorg = "http://localhost:4873/"
|
|
```
|
|
|
|
### Configure options for a specific registry
|
|
|
|
`//<registry_url>/:<key>=<value>` allows you to set options for a specific registry:
|
|
|
|
```ini .npmrc icon="npm"
|
|
# 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, e.g. `btoa(username + ":" + password)`)
|
|
- `email`
|
|
|
|
The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](/runtime/bunfig#install-registry):
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
[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:
|
|
|
|
```ini .npmrc icon="npm"
|
|
link-workspace-packages=true
|
|
```
|
|
|
|
The equivalent `bunfig.toml` option is [`install.linkWorkspacePackages`](/runtime/bunfig#install-linkworkspacepackages):
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
[install]
|
|
linkWorkspacePackages = true
|
|
```
|
|
|
|
### `save-exact`: Save exact versions
|
|
|
|
Always saves exact versions without the `^` prefix:
|
|
|
|
```ini .npmrc icon="npm"
|
|
save-exact=true
|
|
```
|
|
|
|
The equivalent `bunfig.toml` option is [`install.exact`](/runtime/bunfig#install-exact):
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
[install]
|
|
exact = true
|
|
```
|
|
|
|
### `ignore-scripts`: Skip lifecycle scripts
|
|
|
|
Prevents running lifecycle scripts during installation:
|
|
|
|
```ini .npmrc icon="npm"
|
|
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 actually installing:
|
|
|
|
```ini .npmrc icon="npm"
|
|
dry-run=true
|
|
```
|
|
|
|
The equivalent `bunfig.toml` option is [`install.dryRun`](/runtime/bunfig#install-dryrun):
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
[install]
|
|
dryRun = true
|
|
```
|
|
|
|
### `cache`: Configure cache directory
|
|
|
|
Set the cache directory path, or disable caching:
|
|
|
|
```ini .npmrc icon="npm"
|
|
# set a custom cache directory
|
|
cache=/path/to/cache
|
|
|
|
# or disable caching
|
|
cache=false
|
|
```
|
|
|
|
The equivalent `bunfig.toml` option is [`install.cache`](/runtime/bunfig#install-cache):
|
|
|
|
```toml bunfig.toml icon="settings"
|
|
[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:
|
|
|
|
```ini .npmrc icon="npm"
|
|
# 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:
|
|
|
|
```ini .npmrc icon="npm"
|
|
# 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 installed in `node_modules`. Bun supports two different configuration options for compatibility with different package managers.
|
|
|
|
**npm's `install-strategy`:**
|
|
|
|
```ini .npmrc icon="npm"
|
|
# flat node_modules structure (default)
|
|
install-strategy=hoisted
|
|
|
|
# symlinked structure
|
|
install-strategy=linked
|
|
```
|
|
|
|
**pnpm/yarn's `node-linker`:**
|
|
|
|
The `node-linker` option controls the installation mode. Bun supports 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 |
|
|
|
|
```ini .npmrc icon="npm"
|
|
# 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`:
|
|
|
|
```ini .npmrc icon="npm"
|
|
# 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=*
|
|
```
|