bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/{install/lifecycle.md → pm/lifecycle.mdx}

@@ -1,3 +1,8 @@
+---
+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
@@ -7,11 +12,13 @@ Packages on `npm` can define _lifecycle scripts_ in their `package.json`. Some o
 
 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
+```json package.json icon="file-json"
 {
   "name": "my-app",
   "version": "1.0.0",
@@ -21,26 +28,30 @@ The `postinstall` script is particularly important. It's widely used to build or
 }
 ```
 
+---
+
 ## `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-diff
-  {
-    "name": "my-app",
-    "version": "1.0.0",
-+   "trustedDependencies": ["node-sass"]
-  }
+```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
-$ bun install --ignore-scripts
+```bash terminal icon="terminal"
+bun install --ignore-scripts
 ```

package/docs/{install/lockfile.md → pm/lockfile.mdx}

@@ -1,3 +1,8 @@
+---
+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?
@@ -8,38 +13,39 @@ Yes
 
 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
-$ bun install --lockfile-only
+```bash terminal icon="terminal"
+bun install --lockfile-only
 ```
 
-{% callout %}
-**Note** - using `--lockfile-only` will still populate the global install cache with registry metadata and git/tarball dependencies.
-{% /callout %}
+<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
-$ bun install --no-save
+```bash terminal icon="terminal"
+bun install --no-save
 ```
 
 To install a Yarn lockfile _in addition_ to `bun.lock`.
 
-{% codetabs %}
+<CodeGroup>
 
-```bash#CLI flag
-$ bun install --yarn
+```bash terminal icon="terminal"
+bun install --yarn
 ```
 
-```toml#bunfig.toml
+```toml bunfig.toml icon="settings"
 [install.lockfile]
 # whether to save a non-Bun lockfile alongside bun.lock
 # only "yarn" is supported
 print = "yarn"
 ```
 
-{% /codetabs %}
+</CodeGroup>
 
 #### Text-based lockfile
 

package/docs/{install/npmrc.md → pm/npmrc.mdx}

@@ -1,49 +1,55 @@
-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.
+---
+title: .npmrc support
+description:
+---
 
-{% callout %}
+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`](https://bun.com/docs/runtime/bunfig) format, as it provides more flexible options and can let you configure Bun-specific options.
+<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>
 
-{% /callout %}
+---
 
 ## Supported options
 
-### `registry`: Set the default registry
+### 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
+```ini .npmrc icon="npm"
 registry=http://localhost:4873/
 ```
 
-The equivalent `bunfig.toml` option is [`install.registry`](https://bun.com/docs/runtime/bunfig#install-registry):
+The equivalent `bunfig.toml` option is [`install.registry`](/runtime/bunfig#install-registry):
 
-```toml
+```toml bunfig.toml icon="settings"
 install.registry = "http://localhost:4873/"
 ```
 
-### `@<scope>:registry`: Set the registry for a specific scope
+### Set the registry for a specific scope
 
-Allows you to set the registry for a specific scope:
+`@<scope>:registry` allows you to set the registry for a specific scope:
 
-```ini
+```ini .npmrc icon="npm"
 @myorg:registry=http://localhost:4873/
 ```
 
-The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](https://bun.com/docs/runtime/bunfig#install-registry):
+The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](/runtime/bunfig#install-registry):
 
-```toml
+```toml bunfig.toml icon="settings"
 [install.scopes]
 myorg = "http://localhost:4873/"
 ```
 
-### `//<registry_url>/:<key>=<value>`: Configure options for a specific registry
+### Configure options for a specific registry
 
-Allows you to set options for a specific registry:
+`//<registry_url>/:<key>=<value>` allows you to set options for a specific registry:
 
-```ini
+```ini .npmrc icon="npm"
 # set an auth token for the registry
 # ${...} is a placeholder for environment variables
 //http://localhost:4873/:_authToken=${NPM_TOKEN}
@@ -67,9 +73,9 @@ The following options are supported:
 - `_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`](https://bun.com/docs/runtime/bunfig#install-registry):
+The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](/runtime/bunfig#install-registry):
 
-```toml
+```toml bunfig.toml icon="settings"
 [install.scopes]
 myorg = { url = "http://localhost:4873/", username = "myusername", password = "$NPM_PASSWORD" }
 ```
@@ -78,13 +84,13 @@ myorg = { url = "http://localhost:4873/", username = "myusername", password = "$
 
 Controls how workspace packages are installed when available locally:
 
-```ini
+```ini .npmrc icon="npm"
 link-workspace-packages=true
 ```
 
-The equivalent `bunfig.toml` option is [`install.linkWorkspacePackages`](https://bun.com/docs/runtime/bunfig#install-linkworkspacepackages):
+The equivalent `bunfig.toml` option is [`install.linkWorkspacePackages`](/runtime/bunfig#install-linkworkspacepackages):
 
-```toml
+```toml bunfig.toml icon="settings"
 [install]
 linkWorkspacePackages = true
 ```
@@ -93,13 +99,13 @@ linkWorkspacePackages = true
 
 Always saves exact versions without the `^` prefix:
 
-```ini
+```ini .npmrc icon="npm"
 save-exact=true
 ```
 
-The equivalent `bunfig.toml` option is [`install.exact`](https://bun.com/docs/runtime/bunfig#install-exact):
+The equivalent `bunfig.toml` option is [`install.exact`](/runtime/bunfig#install-exact):
 
-```toml
+```toml bunfig.toml icon="settings"
 [install]
 exact = true
 ```

package/docs/{install/overrides.md → pm/overrides.mdx}

@@ -1,20 +1,26 @@
+---
+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-diff#package.json
-  {
-    "name": "my-app",
-    "dependencies": {
-      "foo": "^2.0.0"
-    },
-+   "overrides": {
-+     "bar": "~4.4.0"
-+   }
-  }
+```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
+```json package.json icon="file-json"
 {
   "name": "my-app",
   "dependencies": {
@@ -25,8 +31,7 @@ By default, Bun will install the latest version of all dependencies and metadepe
 
 When you run `bun install`, Bun will install the latest versions of each package.
 
-```
-# tree layout of node_modules
+```txt tree layout of node_modules icon="list-tree"
 node_modules
 ├── foo@1.2.3
 └── bar@4.5.6
@@ -34,24 +39,28 @@ node_modules
 
 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.
 
-{% callout %}
-**Note** — Bun currently only supports top-level `"overrides"`. [Nested overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) are not supported.
-{% /callout %}
-
-```json-diff#package.json
-  {
-    "name": "my-app",
-    "dependencies": {
-      "foo": "^2.0.0"
-    },
-+   "overrides": {
-+     "bar": "~4.4.0"
-+   }
-  }
+<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"`
@@ -60,14 +69,15 @@ The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"over
 
 As with `"overrides"`, _nested resolutions_ are not currently supported.
 
-```json-diff#package.json
-  {
-    "name": "my-app",
-    "dependencies": {
-      "foo": "^2.0.0"
-    },
-+   "resolutions": {
-+     "bar": "~4.4.0"
-+   }
-  }
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  },
+  "resolutions": {
+    // [!code ++]
+    "bar": "~4.4.0" // [!code ++]
+  } // [!code ++]
+}
 ```

package/docs/{install/registries.md → pm/scopes-registries.mdx}

@@ -1,6 +1,11 @@
+---
+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
+```toml bunfig.toml icon="settings"
 [install]
 # set default registry as a string
 registry = "https://registry.npmjs.org"
@@ -12,7 +17,7 @@ registry = "https://username:password@registry.npmjs.org"
 
 To configure a private registry scoped to a particular organization:
 
-```toml
+```toml bunfig.toml icon="settings"
 [install.scopes]
 # registry as string
 "@myorg1" = "https://username:password@registry.myorg.com/"
@@ -27,4 +32,4 @@ To configure a private registry scoped to a particular organization:
 
 ### `.npmrc`
 
-Bun also reads `.npmrc` files, [learn more](https://bun.com/docs/install/npmrc).
+Bun also reads `.npmrc` files, [learn more](/pm/npmrc).

package/docs/{install/security-scanner-api.md → pm/security-scanner-api.mdx}

@@ -1,10 +1,17 @@
+---
+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
+```toml bunfig.toml icon="settings"
 [install.security]
 scanner = "@acme/bun-security-scanner"
 ```
@@ -16,6 +23,8 @@ When configured, Bun will:
 - 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:
@@ -32,6 +41,8 @@ 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.
@@ -40,17 +51,20 @@ Many security companies publish Bun security scanners as npm packages that you c
 
 Install a security scanner from npm:
 
-```bash
-$ bun add -d @acme/bun-security-scanner
+```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>
+  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
+```toml bunfig.toml icon="settings"
 [install.security]
 scanner = "@acme/bun-security-scanner"
 ```
@@ -59,7 +73,7 @@ scanner = "@acme/bun-security-scanner"
 
 Some enterprise scanners might support authentication and/or configuration through environment variables:
 
-```bash
+```bash terminal icon="terminal"
 # This might go in ~/.bashrc, for example
 export SECURITY_API_KEY="your-api-key"
 
@@ -76,6 +90,6 @@ For a complete example with tests and CI setup, see the official template:
 
 ## Related
 
-- [Configuration (bunfig.toml)](/docs/runtime/bunfig#install-security-scanner)
-- [Package Manager](/docs/install)
+- [Configuration (bunfig.toml)](/runtime/bunfig#install-security-scanner)
+- [Package Manager](/installation)
 - [Security Scanner Template](https://github.com/oven-sh/security-scanner-template)

package/docs/{install/workspaces.md → pm/workspaces.mdx}

@@ -1,3 +1,8 @@
+---
+title: "Workspaces"
+description: "Develop complex monorepos with multiple independent packages"
+---
+
 Bun supports [`workspaces`](https://docs.npmjs.com/cli/v9/using-npm/workspaces?v=true#description) in `package.json`. Workspaces make it easy to develop complex software as a _monorepo_ consisting of several independent packages.
 
 It's common for a monorepo to have the following structure:
@@ -37,21 +42,11 @@ In the root `package.json`, the `"workspaces"` key is used to indicate which sub
 }
 ```
 
-{% callout %}
-**Glob support** — Bun supports full glob syntax in `"workspaces"`, including negative patterns (e.g. `!**/excluded/**`). See [here](https://bun.com/docs/api/glob#supported-glob-patterns) for a comprehensive list of supported syntax.
-{% /callout %}
-
-```json
-{
-  "name": "my-project",
-  "version": "1.0.0",
-  "workspaces": [
-    "packages/**",
-    "!packages/**/test/**",
-    "!packages/**/template/**"
-  ]
-}
-```
+<Note>
+  **Glob support** — Bun supports full glob syntax in `"workspaces"` (see [here](/runtime/glob#supported-glob-patterns)
+  for a comprehensive list of supported syntax), _except_ for exclusions (e.g. `!**/excluded/**`), which are not
+  implemented yet.
+</Note>
 
 Each workspace has it's own `package.json`. When referencing other packages in the monorepo, semver or workspace protocols (e.g. `workspace:*`) can be used as the version field in your `package.json`.
 
@@ -69,10 +64,10 @@ Each workspace has it's own `package.json`. When referencing other packages in t
 
 ```bash
 # Install dependencies for all workspaces starting with `pkg-` except for `pkg-c`
-$ bun install --filter "pkg-*" --filter "!pkg-c"
+bun install --filter "pkg-*" --filter "!pkg-c"
 
 # Paths can also be used. This is equivalent to the command above.
-$ bun install --filter "./packages/pkg-*" --filter "!pkg-c" # or --filter "!./packages/pkg-c"
+bun install --filter "./packages/pkg-*" --filter "!pkg-c" # or --filter "!./packages/pkg-c"
 ```
 
 When publishing, `workspace:` versions are replaced by the package's `package.json` version,
@@ -93,7 +88,7 @@ Workspaces have a couple major benefits.
 
 - **Code can be split into logical parts.** If one package relies on another, you can simply add it as a dependency in `package.json`. If package `b` depends on `a`, `bun install` will install your local `packages/a` directory into `node_modules` instead of downloading it from the npm registry.
 - **Dependencies can be de-duplicated.** If `a` and `b` share a common dependency, it will be _hoisted_ to the root `node_modules` directory. This reduces redundant disk usage and minimizes "dependency hell" issues associated with having multiple versions of a package installed simultaneously.
-- **Run scripts in multiple packages.** You can use the [`--filter` flag](https://bun.com/docs/cli/filter) to easily run `package.json` scripts in multiple packages in your workspace, or `--workspaces` to run scripts across all workspaces.
+- **Run scripts in multiple packages.** You can use the [`--filter` flag](/pm/filter) to easily run `package.json` scripts in multiple packages in your workspace, , or `--workspaces` to run scripts across all workspaces.
 
 ## Share versions with Catalogs
 
@@ -101,14 +96,14 @@ When many packages need the same dependency versions, catalogs let you define
 those versions once in the root `package.json` and reference them from your
 workspaces using the `catalog:` protocol. Updating the catalog automatically
 updates every package that references it. See
-[Catalogs](https://bun.com/docs/install/catalogs) for details.
+[Catalogs](/pm/catalogs) for details.
 
-{% callout %}
+<Note>
 ⚡️ **Speed** — Installs are fast, even for big monorepos. Bun installs the [Remix](https://github.com/remix-run/remix) monorepo in about `500ms` on Linux.
 
 - 28x faster than `npm install`
 - 12x faster than `yarn install` (v1)
 - 8x faster than `pnpm install`
 
-{% image src="https://user-images.githubusercontent.com/709451/212829600-77df9544-7c9f-4d8d-a984-b2cd0fd2aa52.png" /%}
-{% /callout %}
+<Image src="https://user-images.githubusercontent.com/709451/212829600-77df9544-7c9f-4d8d-a984-b2cd0fd2aa52.png" />
+</Note>

package/docs/project/{benchmarking.md → benchmarking.mdx}

@@ -1,3 +1,8 @@
+---
+title: Benchmarking
+description: How to benchmark Bun
+---
+
 Bun is designed for speed. Hot paths are extensively profiled and benchmarked. The source code for all of Bun's public benchmarks can be found in the [`/bench`](https://github.com/oven-sh/bun/tree/main/bench) directory of the Bun repo.
 
 ## Measuring time
@@ -22,8 +27,6 @@ When writing your own benchmarks, it's important to choose the right tool.
 
 Bun has two heaps. One heap is for the JavaScript runtime and the other heap is for everything else.
 
-{% anchor id="bunjsc" /%}
-
 ### JavaScript heap stats
 
 The `bun:jsc` module exposes a few functions for measuring memory usage:
@@ -33,9 +36,9 @@ import { heapStats } from "bun:jsc";
 console.log(heapStats());
 ```
 
-{% details summary="View example statistics"  %}
+<Accordion title="View example statistics">
 
-```ts
+```ts expandable icon="/icons/typescript.svg"
 {
   heapSize: 1657575,
   heapCapacity: 2872775,
@@ -138,13 +141,13 @@ console.log(heapStats());
 }
 ```
 
-{% /details %}
+</Accordion>
 
 JavaScript is a garbage-collected language, not reference counted. It's normal and correct for objects to not be freed immediately in all cases, though it's not normal for objects to never be freed.
 
 To force garbage collection to run manually:
 
-```js
+```ts
 Bun.gc(true); // synchronous
 Bun.gc(false); // asynchronous
 ```
@@ -165,22 +168,34 @@ To view the snapshot, open the `heap.json` file in Safari's Developer Tools (or
 3. Click "JavaScript Allocations" in the menu on the left. It might not be visible until you click the pencil icon to show all the timelines
 4. Click "Import" and select your heap snapshot JSON
 
-{% image alt="Import heap json" src="https://user-images.githubusercontent.com/709451/204428943-ba999e8f-8984-4f23-97cb-b4e3e280363e.png" caption="Importing a heap snapshot" /%}
+<Frame>
+  <img
+    src="https://user-images.githubusercontent.com/709451/204428943-ba999e8f-8984-4f23-97cb-b4e3e280363e.png"
+    alt="Importing a heap snapshot"
+  />
+</Frame>
 
 Once imported, you should see something like this:
 
-{% image alt="Viewing heap snapshot in Safari" src="https://user-images.githubusercontent.com/709451/204429337-b0d8935f-3509-4071-b991-217794d1fb27.png" caption="Viewing heap snapshot in Safari Dev Tools" /%}
+<Frame>
+  <img
+    alt="Viewing heap snapshot in Safari"
+    src="https://user-images.githubusercontent.com/709451/204429337-b0d8935f-3509-4071-b991-217794d1fb27.png"
+    caption="Viewing heap snapshot in Safari Dev Tools"
+  />
+</Frame>
 
-> The [web debugger](https://bun.com/docs/runtime/debugger#inspect) also offers the timeline feature which allows you to track and examine the memory usage of the running debug session.
+> The [web debugger](/runtime/debugger#inspect) also offers the timeline feature which allows you to track and examine the memory usage of the running debug session.
 
 ### Native heap stats
 
 Bun uses mimalloc for the other heap. To report a summary of non-JavaScript memory usage, set the `MIMALLOC_SHOW_STATS=1` environment variable. and stats will print on exit.
 
-```js
+```sh terminal icon="terminal"
 MIMALLOC_SHOW_STATS=1 bun script.js
+```
 
-# will show something like this:
+```txt
 heap stats:    peak      total      freed    current       unit      count
   reserved:   64.0 MiB   64.0 MiB      0       64.0 MiB                        not all freed!
  committed:   64.0 MiB   64.0 MiB      0       64.0 MiB                        not all freed!