bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/pm/isolated-installs.mdx

@@ -0,0 +1,205 @@
+---
+title: "Isolated installs"
+description: "Strict dependency isolation similar to pnpm's approach"
+---
+
+Bun provides an alternative package installation strategy called **isolated installs** that creates strict dependency isolation similar to pnpm's approach. This mode prevents phantom dependencies and ensures reproducible, deterministic builds.
+
+This is the default installation strategy for monorepo projects.
+
+## What are isolated installs?
+
+Isolated installs create a non-hoisted dependency structure where packages can only access their explicitly declared dependencies. This differs from the traditional "hoisted" installation strategy used by npm and Yarn, where dependencies are flattened into a shared `node_modules` directory.
+
+### Key benefits
+
+- **Prevents phantom dependencies** — Packages cannot accidentally import dependencies they haven't declared
+- **Deterministic resolution** — Same dependency tree regardless of what else is installed
+- **Better for monorepos** — Workspace isolation prevents cross-contamination between packages
+- **Reproducible builds** — More predictable resolution behavior across environments
+
+## Using isolated installs
+
+### Command line
+
+Use the `--linker` flag to specify the installation strategy:
+
+```bash terminal icon="terminal"
+# Use isolated installs
+bun install --linker isolated
+
+# Use traditional hoisted installs
+bun install --linker hoisted
+```
+
+### Configuration file
+
+Set the default linker strategy in your `bunfig.toml` or globally in `$HOME/.bunfig.toml`:
+
+```toml bunfig.toml icon="settings"
+[install]
+linker = "isolated"
+```
+
+### Default behavior
+
+- For monorepo projects, Bun uses the **isolated** installation strategy by default.
+- For single-project projects, Bun uses the **hoisted** installation strategy by default.
+
+You can override the default behavior by explicitly specifying the `--linker` flag or setting it in your configuration file.
+
+## How isolated installs work
+
+### Directory structure
+
+Instead of hoisting dependencies, isolated installs create a two-tier structure:
+
+```bash tree layout of node_modules icon="list-tree"
+node_modules/
+├── .bun/                          # Central package store
+│   ├── package@1.0.0/             # Versioned package installations
+│   │   └── node_modules/
+│   │       └── package/           # Actual package files
+│   ├── @scope+package@2.1.0/      # Scoped packages (+ replaces /)
+│   │   └── node_modules/
+│   │       └── @scope/
+│   │           └── package/
+│   └── ...
+└── package-name -> .bun/package@1.0.0/node_modules/package  # Symlinks
+```
+
+### Resolution algorithm
+
+1. **Central store** — All packages are installed in `node_modules/.bun/package@version/` directories
+2. **Symlinks** — Top-level `node_modules` contains symlinks pointing to the central store
+3. **Peer resolution** — Complex peer dependencies create specialized directory names
+4. **Deduplication** — Packages with identical package IDs and peer dependency sets are shared
+
+### Workspace handling
+
+In monorepos, workspace dependencies are handled specially:
+
+- **Workspace packages** — Symlinked directly to their source directories, not the store
+- **Workspace dependencies** — Can access other workspace packages in the monorepo
+- **External dependencies** — Installed in the isolated store with proper isolation
+
+## Comparison with hoisted installs
+
+| Aspect                    | Hoisted (npm/Yarn)                         | Isolated (pnpm-like)                    |
+| ------------------------- | ------------------------------------------ | --------------------------------------- |
+| **Dependency access**     | Packages can access any hoisted dependency | Packages only see declared dependencies |
+| **Phantom dependencies**  | ❌ Possible                                | ✅ Prevented                            |
+| **Disk usage**            | ✅ Lower (shared installs)                 | ✅ Similar (uses symlinks)              |
+| **Determinism**           | ❌ Less deterministic                      | ✅ More deterministic                   |
+| **Node.js compatibility** | ✅ Standard behavior                       | ✅ Compatible via symlinks              |
+| **Best for**              | Single projects, legacy code               | Monorepos, strict dependency management |
+
+## Advanced features
+
+### Peer dependency handling
+
+Isolated installs handle peer dependencies through sophisticated resolution:
+
+```bash tree layout of node_modules icon="list-tree"
+# Package with peer dependencies creates specialized paths
+node_modules/.bun/package@1.0.0_react@18.2.0/
+```
+
+The directory name encodes both the package version and its peer dependency versions, ensuring each unique combination gets its own installation.
+
+### Backend strategies
+
+Bun uses different file operation strategies for performance:
+
+- **Clonefile** (macOS) — Copy-on-write filesystem clones for maximum efficiency
+- **Hardlink** (Linux/Windows) — Hardlinks to save disk space
+- **Copyfile** (fallback) — Full file copies when other methods aren't available
+
+### Debugging isolated installs
+
+Enable verbose logging to understand the installation process:
+
+```bash terminal icon="terminal"
+bun install --linker isolated --verbose
+```
+
+This shows:
+
+- Store entry creation
+- Symlink operations
+- Peer dependency resolution
+- Deduplication decisions
+
+## Troubleshooting
+
+### Compatibility issues
+
+Some packages may not work correctly with isolated installs due to:
+
+- **Hardcoded paths** — Packages that assume a flat `node_modules` structure
+- **Dynamic imports** — Runtime imports that don't follow Node.js resolution
+- **Build tools** — Tools that scan `node_modules` directly
+
+If you encounter issues, you can:
+
+1. **Switch to hoisted mode** for specific projects:
+
+   ```bash terminal icon="terminal"
+   bun install --linker hoisted
+   ```
+
+2. **Report compatibility issues** to help improve isolated install support
+
+### Performance considerations
+
+- **Install time** — May be slightly slower due to symlink operations
+- **Disk usage** — Similar to hoisted (uses symlinks, not file copies)
+- **Memory usage** — Higher during install due to complex peer resolution
+
+## Migration guide
+
+### From npm/Yarn
+
+```bash terminal icon="terminal"
+# Remove existing node_modules and lockfiles
+rm -rf node_modules package-lock.json yarn.lock
+
+# Install with isolated linker
+bun install --linker isolated
+```
+
+### From pnpm
+
+Isolated installs are conceptually similar to pnpm, so migration should be straightforward:
+
+```bash terminal icon="terminal"
+# Remove pnpm files
+$ rm -rf node_modules pnpm-lock.yaml
+
+# Install with Bun's isolated linker
+bun install --linker isolated
+```
+
+The main difference is that Bun uses symlinks in `node_modules` while pnpm uses a global store with symlinks.
+
+## When to use isolated installs
+
+**Use isolated installs when:**
+
+- Working in monorepos with multiple packages
+- Strict dependency management is required
+- Preventing phantom dependencies is important
+- Building libraries that need deterministic dependencies
+
+**Use hoisted installs when:**
+
+- Working with legacy code that assumes flat `node_modules`
+- Compatibility with existing build tools is required
+- Working in environments where symlinks aren't well supported
+- You prefer the simpler traditional npm behavior
+
+## Related documentation
+
+- [Package manager > Workspaces](/pm/workspaces) — Monorepo workspace management
+- [Package manager > Lockfile](/pm/lockfile) — Understanding Bun's lockfile format
+- [CLI > install](/pm/cli/install) — Complete `bun install` command reference

package/docs/pm/lifecycle.mdx

@@ -0,0 +1,57 @@
+---
+title: "Lifecycle scripts"
+description: "How Bun handles package lifecycle scripts securely"
+---
+
+Packages on `npm` can define _lifecycle scripts_ in their `package.json`. Some of the most common are below, but there are [many others](https://docs.npmjs.com/cli/v10/using-npm/scripts).
+
+- `preinstall`: Runs before the package is installed
+- `postinstall`: Runs after the package is installed
+- `preuninstall`: Runs before the package is uninstalled
+- `prepublishOnly`: Runs before the package is published
+
+These scripts are arbitrary shell commands that the package manager is expected to read and execute at the appropriate time. But executing arbitrary scripts represents a potential security risk, so—unlike other `npm` clients—Bun does not execute arbitrary lifecycle scripts by default.
+
+---
+
+## `postinstall`
+
+The `postinstall` script is particularly important. It's widely used to build or install platform-specific binaries for packages that are implemented as [native Node.js add-ons](https://nodejs.org/api/addons.html). For example, `node-sass` is a popular package that uses `postinstall` to build a native binary for Sass.
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "dependencies": {
+    "node-sass": "^6.0.1"
+  }
+}
+```
+
+---
+
+## `trustedDependencies`
+
+Instead of executing arbitrary scripts, Bun uses a "default-secure" approach. You can add certain packages to an allow list, and Bun will execute lifecycle scripts for those packages. To tell Bun to allow lifecycle scripts for a particular package, add the package name to `trustedDependencies` array in your `package.json`.
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "trustedDependencies": ["node-sass"] // [!code ++]
+}
+```
+
+Once added to `trustedDependencies`, install/re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`.
+
+As of Bun v1.0.16, the top 500 npm packages with lifecycle scripts are allowed by default. You can see the full list [here](https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt).
+
+---
+
+## `--ignore-scripts`
+
+To disable lifecycle scripts for all packages, use the `--ignore-scripts` flag.
+
+```bash terminal icon="terminal"
+bun install --ignore-scripts
+```

package/docs/pm/lockfile.mdx

@@ -0,0 +1,64 @@
+---
+title: "Lockfile"
+description: "Bun's lockfile format and configuration"
+---
+
+Running `bun install` will create a lockfile called `bun.lock`.
+
+#### Should it be committed to git?
+
+Yes
+
+#### Generate a lockfile without installing?
+
+To generate a lockfile without installing to `node_modules` you can use the `--lockfile-only` flag. The lockfile will always be saved to disk, even if it is up-to-date with the `package.json`(s) for your project.
+
+```bash terminal icon="terminal"
+bun install --lockfile-only
+```
+
+<Note>
+  Using `--lockfile-only` will still populate the global install cache with registry metadata and git/tarball
+  dependencies.
+</Note>
+
+#### Can I opt out?
+
+To install without creating a lockfile:
+
+```bash terminal icon="terminal"
+bun install --no-save
+```
+
+To install a Yarn lockfile _in addition_ to `bun.lock`.
+
+<CodeGroup>
+
+```bash terminal icon="terminal"
+bun install --yarn
+```
+
+```toml bunfig.toml icon="settings"
+[install.lockfile]
+# whether to save a non-Bun lockfile alongside bun.lock
+# only "yarn" is supported
+print = "yarn"
+```
+
+</CodeGroup>
+
+#### Text-based lockfile
+
+Bun v1.2 changed the default lockfile format to the text-based `bun.lock`. Existing binary `bun.lockb` lockfiles can be migrated to the new format by running `bun install --save-text-lockfile --frozen-lockfile --lockfile-only` and deleting `bun.lockb`.
+
+More information about the new lockfile format can be found on [our blogpost](https://bun.com/blog/bun-lock-text-lockfile).
+
+#### Automatic lockfile migration
+
+When running `bun install` in a project without a `bun.lock`, Bun automatically migrates existing lockfiles:
+
+- `yarn.lock` (v1)
+- `package-lock.json` (npm)
+- `pnpm-lock.yaml` (pnpm)
+
+The original lockfile is preserved and can be removed manually after verification.

package/docs/pm/npmrc.mdx

@@ -0,0 +1,111 @@
+---
+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)`)
+
+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
+```

package/docs/pm/overrides.mdx

@@ -0,0 +1,83 @@
+---
+title: "Overrides and resolutions"
+description: "Control metadependency versions with npm overrides and Yarn resolutions"
+---
+
+Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies.
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  },
+  "overrides": {
+    // [!code ++]
+    "bar": "~4.4.0" // [!code ++]
+  } // [!code ++]
+}
+```
+
+By default, Bun will install the latest version of all dependencies and metadependencies, according to the ranges specified in each package's `package.json`. Let's say you have a project with one dependency, `foo`, which in turn has a dependency on `bar`. This means `bar` is a _metadependency_ of our project.
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  }
+}
+```
+
+When you run `bun install`, Bun will install the latest versions of each package.
+
+```txt tree layout of node_modules icon="list-tree"
+node_modules
+├── foo@1.2.3
+└── bar@4.5.6
+```
+
+But what if a security vulnerability was introduced in `bar@4.5.6`? We may want a way to pin `bar` to an older version that doesn't have the vulnerability. This is where `"overrides"`/`"resolutions"` come in.
+
+---
+
+## `"overrides"`
+
+Add `bar` to the `"overrides"` field in `package.json`. Bun will defer to the specified version range when determining which version of `bar` to install, whether it's a dependency or a metadependency.
+
+<Note>
+  Bun currently only supports top-level `"overrides"`. [Nested
+  overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) are not supported.
+</Note>
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  },
+  "overrides": {
+    // [!code ++]
+    "bar": "~4.4.0" // [!code ++]
+  } // [!code ++]
+}
+```
+
+## `"resolutions"`
+
+The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"overrides"`. Bun supports this feature to make migration from Yarn easier.
+
+As with `"overrides"`, _nested resolutions_ are not currently supported.
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  },
+  "resolutions": {
+    // [!code ++]
+    "bar": "~4.4.0" // [!code ++]
+  } // [!code ++]
+}
+```

package/docs/pm/scopes-registries.mdx

@@ -0,0 +1,35 @@
+---
+title: "Scopes and registries"
+description: "Configure private registries and scoped packages"
+---
+
+The default registry is `registry.npmjs.org`. This can be globally configured in `bunfig.toml`:
+
+```toml bunfig.toml icon="settings"
+[install]
+# set default registry as a string
+registry = "https://registry.npmjs.org"
+# set a token
+registry = { url = "https://registry.npmjs.org", token = "123456" }
+# set a username/password
+registry = "https://username:password@registry.npmjs.org"
+```
+
+To configure a private registry scoped to a particular organization:
+
+```toml bunfig.toml icon="settings"
+[install.scopes]
+# registry as string
+"@myorg1" = "https://username:password@registry.myorg.com/"
+
+# registry with username/password
+# you can reference environment variables
+"@myorg2" = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" }
+
+# registry with token
+"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
+```
+
+### `.npmrc`
+
+Bun also reads `.npmrc` files, [learn more](/pm/npmrc).

package/docs/pm/security-scanner-api.mdx

@@ -0,0 +1,95 @@
+---
+title: Security Scanner API
+description:
+---
+
+Bun's package manager can scan packages for security vulnerabilities before installation, helping protect your applications from supply chain attacks and known vulnerabilities.
+
+---
+
+## Quick Start
+
+Configure a security scanner in your `bunfig.toml`:
+
+```toml bunfig.toml icon="settings"
+[install.security]
+scanner = "@acme/bun-security-scanner"
+```
+
+When configured, Bun will:
+
+- Scan all packages before installation
+- Display security warnings and advisories
+- Cancel installation if critical vulnerabilities are found
+- Automatically disable auto-install for security
+
+---
+
+## How It Works
+
+Security scanners analyze packages during `bun install`, `bun add`, and other package operations. They can detect:
+
+- Known security vulnerabilities (CVEs)
+- Malicious packages
+- License compliance issues
+- ...and more!
+
+### Security Levels
+
+Scanners report issues at two severity levels:
+
+- **`fatal`** - Installation stops immediately, exits with non-zero code
+- **`warn`** - In interactive terminals, prompts to continue; in CI, exits immediately
+
+---
+
+## Using Pre-built Scanners
+
+Many security companies publish Bun security scanners as npm packages that you can install and use immediately.
+
+### Installing a Scanner
+
+Install a security scanner from npm:
+
+```bash terminal icon="terminal"
+bun add -d @acme/bun-security-scanner
+```
+
+<Note>
+  Consult your security scanner's documentation for their specific package name and installation instructions. Most
+  scanners will be installed with `bun add`.
+</Note>
+
+### Configuring the Scanner
+
+After installation, configure it in your `bunfig.toml`:
+
+```toml bunfig.toml icon="settings"
+[install.security]
+scanner = "@acme/bun-security-scanner"
+```
+
+### Enterprise Configuration
+
+Some enterprise scanners might support authentication and/or configuration through environment variables:
+
+```bash terminal icon="terminal"
+# This might go in ~/.bashrc, for example
+export SECURITY_API_KEY="your-api-key"
+
+# The scanner will now use these credentials automatically
+bun install
+```
+
+Consult your security scanner's documentation to learn which environment variables to set and if any additional configuration is required.
+
+### Authoring your own scanner
+
+For a complete example with tests and CI setup, see the official template:
+[github.com/oven-sh/security-scanner-template](https://github.com/oven-sh/security-scanner-template)
+
+## Related
+
+- [Configuration (bunfig.toml)](/runtime/bunfig#install-security-scanner)
+- [Package Manager](/installation)
+- [Security Scanner Template](https://github.com/oven-sh/security-scanner-template)