pm

103 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

Global store real-world cold to warm timings

Real-world repository benchmark results on macOS arm64: cal.com (~3,580 packages) 37.4 s cold to 4.7 s warm; remix (~1,750 packages) 23.1 s cold to 2.0 s warm; excalidraw (~1,332 packages) 5.9 s cold to 1.1 s warm; hono (~790 packages) 4.5 s cold to 1.3 s warm; next build/create-next-app (~382 packages) 1.0 s cold to 0.35 s warm.

Global store node_modules size reduction

The global virtual store reduces node_modules size from hundreds of megabytes per project to approximately 5 MB of symlinks per project. For five cloned copies of the same project, the difference is roughly 2 GB of duplicated files versus 400 MB total with the global store. The shared cache directory on disk remains at full size (391 MB in the benchmark fixture).

Enable global store in bunfig.toml

To enable the global virtual store for a project, add the following configuration to bunfig.toml: [install] linker = "isolated" globalStore = true The global store only applies to the isolated linker and is not used by the hoisted linker.

Enable global store via environment variable

To enable the global virtual store per invocation, use the environment variable BUN_INSTALL_GLOBAL_STORE=1 with the isolated linker: BUN_INSTALL_GLOBAL_STORE=1 bun install --linker isolated

Global store disabled by default

The global virtual store is off by default. To explicitly opt out, set globalStore = false in bunfig.toml or set BUN_INSTALL_GLOBAL_STORE=0 in the environment.

Packages that don't use global store: patched packages

Packages with a patch applied via bun patch fall back to per-project node_modules/.bun/<storepath>/ directory because the patched contents are project-specific and cannot be safely shared.

Global virtual store overview

The global virtual store is a feature that installs packages once in a shared cache and creates symlinks from each project's node_modules into that cache. This contrasts with the default behavior where each project gets its own complete copy of all dependencies. Package files live in one shared location at ~/.bun/install/cache/links/, and each project's node_modules contains a thin tree of symlinks pointing to these shared files.

trustedDependencies empty array disables all lifecycle scripts

Set trustedDependencies: [] when you want to opt out of the default allow list entirely without passing --ignore-scripts on every install. If you define trustedDependencies with an explicit list, include any packages from the default list whose lifecycle scripts you still need (for example, sharp or esbuild) — they are no longer trusted implicitly.

ignore-scripts .npmrc setting

Set ignore-scripts=true in .npmrc to disable lifecycle scripts by default.

Bun default-secure lifecycle scripts

Bun does not execute arbitrary lifecycle scripts by default, unlike other npm clients. This is a security-first approach.

Lifecycle scripts overview

Packages on npm can define lifecycle scripts in their package.json. Common lifecycle scripts include preinstall (runs before package is installed), postinstall (runs after package is installed), preuninstall (runs before package is uninstalled), and prepublishOnly (runs before package is published). These scripts are arbitrary shell commands.

trustedDependencies field

To allow lifecycle scripts for a particular package, add its name to the trustedDependencies array in package.json. After adding the package to trustedDependencies, install or re-install it for Bun to read the field and run its lifecycle scripts.

Default trusted dependencies list applies only to npm sources

The default trusted dependencies list only applies to packages installed from npm. For packages from other sources such as file:, link:, git:, or github: dependencies, you must explicitly add them to trustedDependencies to run their lifecycle scripts, even if the package name matches an entry in the default list.

trustedDependencies replaces default list

Defining trustedDependencies in package.json replaces the default list rather than extending it. Three modes apply: (1) trustedDependencies omitted — packages in Bun's built-in list (npm sources only) are allowed; (2) trustedDependencies with explicit list — only the listed packages are allowed, the default list is ignored; (3) trustedDependencies: [] — no packages are allowed, including none from the default list.

Overrides field syntax and purpose

The 'overrides' field in package.json allows you to specify a version range for metadependencies. When you add a package to 'overrides', Bun defers to the specified version range when determining which version to install, whether it is a direct dependency or a metadependency.

Only top-level overrides are supported

Bun only supports top-level 'overrides' in package.json, not nested overrides as npm supports.

Resolutions field as Yarn alternative

Bun supports 'resolutions' as Yarn's alternative to 'overrides', with similar syntax and functionality. Nested resolutions are not supported.

Overrides example in package.json

Example of using overrides to pin a metadependency version: ```json { "name": "my-app", "dependencies": { "foo": "^2.0.0" }, "overrides": { "bar": "~4.4.0" } } ``` This pins bar to the ~4.4.0 version range regardless of what foo specifies.

Resolutions example in package.json

Example of using resolutions (Yarn-style) to pin a metadependency version: ```json { "name": "my-app", "dependencies": { "foo": "^2.0.0" }, "resolutions": { "bar": "~4.4.0" } } ``` This pins bar to the ~4.4.0 version range using Yarn's resolutions syntax.

Bun supports npm overrides and Yarn resolutions for metadependencies

Bun supports both npm's 'overrides' and Yarn's 'resolutions' fields in package.json to control the versions of metadependencies, which are the dependencies of your project's dependencies.

ca and cafile options for certificates

Configure custom CA certificates in .npmrc using the ca option for single or multiple certificates (ca[] for multiple) with the certificate content, or cafile=/path/to/ca-bundle.crt to specify a path to a CA certificate file.

.npmrc support in Bun

Bun loads configuration options from .npmrc files, allowing reuse of existing registry and scope configuration from npm. Bun recommends migrating .npmrc files to bunfig.toml format, which supports more options including Bun-specific ones.

Default registry configuration

Bun resolves packages from npm's official registry at https://registry.npmjs.org/ by default. To change the default registry, set the registry option in .npmrc to a different URL, such as registry=http://localhost:4873/. The equivalent bunfig.toml option is install.registry.

Scope-specific registry configuration

Use @<scope>:registry in .npmrc to set a registry for a specific scope. For example, @myorg:registry=http://localhost:4873/ sets the registry for the @myorg scope. The equivalent bunfig.toml option is to add an entry in install.scopes with the scope name as the key and the registry URL as the value.

Registry-specific authentication options

Use //<registry_url>/:<key>=<value> syntax in .npmrc to set authentication options for a specific registry. Supported options are: _authToken, username, _password (base64 encoded), _auth (base64 encoded username:password), and email. Environment variables can be referenced using ${VARIABLE_NAME} syntax. The equivalent bunfig.toml option is to add entries in install.scopes with an object containing url, username, and password keys.

link-workspace-packages option

The link-workspace-packages option in .npmrc controls how workspace packages are installed when available locally. Set link-workspace-packages=true to enable linking. The equivalent bunfig.toml option is install.linkWorkspacePackages.

save-exact option

The save-exact option in .npmrc, when set to true, always saves exact versions without the ^ prefix. The equivalent bunfig.toml option is install.exact.

ignore-scripts option

The ignore-scripts option in .npmrc, when set to true, prevents running lifecycle scripts during installation. This is equivalent to using the --ignore-scripts flag with bun install.

dry-run option

The dry-run option in .npmrc, when set to true, shows what would be installed without actually installing anything. The equivalent bunfig.toml option is install.dryRun.

cache option configuration

The cache option in .npmrc can be used to set a custom cache directory path (cache=/path/to/cache) or to disable caching (cache=false). The equivalent bunfig.toml options are install.cache.dir to set a custom directory or install.cache.disable to disable caching.

omit and include options for dependency types

Use omit and include options in .npmrc to control which dependency types are installed. Valid values are dev, peer, and optional. Use omit=dev or omit[]=dev and omit[]=optional to omit multiple types. The include option overrides omit settings.

install-strategy option for node_modules layout

The install-strategy option in .npmrc controls how packages are laid out in node_modules. Set install-strategy=hoisted (default) for a flat node_modules structure or install-strategy=linked for a symlinked structure.

node-linker option for installation mode

The node-linker option in .npmrc controls the installation mode. Bun accepts values from both pnpm and yarn. Values isolated and pnpm create symlinked/isolated structures; values hoisted and node-modules create flat structures. For isolated linker only, set hoist=false to disable the node_modules/.bun/node_modules fallback.

public-hoist-pattern and hoist-pattern options

Use public-hoist-pattern in .npmrc to specify which packages are hoisted to the root node_modules (e.g., public-hoist-pattern=*eslint*). Multiple patterns can be specified using array syntax (public-hoist-pattern[]=*eslint*, public-hoist-pattern[]=*prettier*). The hoist-pattern option controls general hoisting behavior.

Configure scoped private registry in bunfig.toml

Use the [install.scopes] section in bunfig.toml to configure registries for specific package scopes. Each scope (e.g., "@myorg") can be mapped to a registry URL.

Scoped registry as string in bunfig.toml

In bunfig.toml under [install.scopes], configure a scoped registry as a string: "@myorg1" = "https://username:password@registry.myorg.com/"

Scoped registry with username and password in bunfig.toml

In bunfig.toml under [install.scopes], configure a scoped registry with explicit username and password: "@myorg2" = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" }. Environment variables like $NPM_PASS can be referenced.

Scoped registry with token in bunfig.toml

In bunfig.toml under [install.scopes], configure a scoped registry with a token: "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }. Environment variables can be referenced.

Bun reads .npmrc files

Bun also reads .npmrc files for registry configuration.

Default registry in bunfig.toml

The default registry is registry.npmjs.org. To change it globally, set the registry in the [install] section of bunfig.toml.

Configure registry as string in bunfig.toml

In bunfig.toml under [install], set registry as a string: registry = "https://registry.npmjs.org"

Configure registry with token in bunfig.toml

In bunfig.toml under [install], set registry as an object with url and token: registry = { url = "https://registry.npmjs.org", token = "123456" }

Configure registry with username and password in bunfig.toml

In bunfig.toml under [install], set registry as a URL with embedded credentials: registry = "https://username:password@registry.npmjs.org"

Give your agent this brain