bun-types 1.3.2-canary.20251105T140650 → 1.3.2

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

@@ -1,40 +1,50 @@
-The `bun` CLI contains a Node.js-compatible package manager designed to be a dramatically faster replacement for `npm`, `yarn`, and `pnpm`. It's a standalone tool that will work in pre-existing Node.js projects; if your project has a `package.json`, `bun install` can help you speed up your workflow.
+---
+title: "bun install"
+description: "Install packages with Bun's fast package manager"
+---
 
-{% callout %}
+import Install from "/snippets/cli/install.mdx";
 
-**⚡️ 25x faster** — Switch from `npm install` to `bun install` in any Node.js project to make your installations up to 25x faster.
+## Basic Usage
 
-{% image src="https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png" height="200" /%}
+```bash terminal icon="terminal"
+bun install react
+bun install react@19.1.1 # specific version
+bun install react@latest # specific tag
+```
 
-{% /callout %}
+The `bun` CLI contains a Node.js-compatible package manager designed to be a dramatically faster replacement for `npm`, `yarn`, and `pnpm`. It's a standalone tool that will work in pre-existing Node.js projects; if your project has a `package.json`, `bun install` can help you speed up your workflow.
 
-{% callout %}
+<Note>
 
-**💾 Disk efficient** — Bun install stores all packages in a global cache (`~/.bun/install/cache/`) and creates hardlinks (Linux) or copy-on-write clones (macOS) to `node_modules`. This means duplicate packages across projects point to the same underlying data, taking up virtually no extra disk space.
+**⚡️ 25x faster** — Switch from `npm install` to `bun install` in any Node.js project to make your installations up to 25x faster.
 
-For more details, see [Package manager > Global cache](https://bun.com/docs/install/cache).
+<Frame>
+  ![Bun installation speed
+  comparison](https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png)
+</Frame>
 
-{% /callout %}
+</Note>
 
-{% details summary="For Linux users" %}
+<Accordion title="For Linux users">
 The recommended minimum Linux Kernel version is 5.6. If you're on Linux kernel 5.1 - 5.5, `bun install` will work, but HTTP requests will be slow due to a lack of support for io_uring's `connect()` operation.
 
 If you're using Ubuntu 20.04, here's how to install a [newer kernel](https://wiki.ubuntu.com/Kernel/LTSEnablementStack):
 
-```bash
+```bash terminal icon="terminal"
 # If this returns a version >= 5.6, you don't need to do anything
-$ uname -r
+uname -r
 
 # Install the official Ubuntu hardware enablement kernel
-$ sudo apt install --install-recommends linux-generic-hwe-20.04
+sudo apt install --install-recommends linux-generic-hwe-20.04
 ```
 
-{% /details %}
+</Accordion>
 
 To install all dependencies of a project:
 
-```bash
-$ bun install
+```bash terminal icon="terminal"
+bun install
 ```
 
 Running `bun install` will:
@@ -43,89 +53,105 @@ Running `bun install` will:
 - **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies.
 - **Write** a `bun.lock` lockfile to the project root.
 
+---
+
 ## Logging
 
 To modify logging verbosity:
 
-```bash
-$ bun install --verbose # debug logging
-$ bun install --silent  # no logging
+```bash terminal icon="terminal"
+bun install --verbose # debug logging
+bun install --silent  # no logging
 ```
 
+---
+
 ## Lifecycle scripts
 
 Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts like `postinstall` for installed dependencies. Executing arbitrary scripts represents a potential security risk.
 
 To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
 
-```json-diff
-  {
-    "name": "my-app",
-    "version": "1.0.0",
-+   "trustedDependencies": ["my-trusted-package"]
-  }
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "trustedDependencies": ["my-trusted-package"] // [!code ++]
+}
 ```
 
 Then re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`.
 
 Lifecycle scripts will run in parallel during installation. To adjust the maximum number of concurrent scripts, use the `--concurrent-scripts` flag. The default is two times the reported cpu count or GOMAXPROCS.
 
-```bash
-$ bun install --concurrent-scripts 5
+```bash terminal icon="terminal"
+bun install --concurrent-scripts 5
 ```
 
+---
+
 ## Workspaces
 
-Bun supports `"workspaces"` in package.json. For complete documentation refer to [Package manager > Workspaces](https://bun.com/docs/install/workspaces).
+Bun supports `"workspaces"` in package.json. For complete documentation refer to [Package manager > Workspaces](/pm/workspaces).
 
-```json#package.json
+```json package.json icon="file-json"
 {
   "name": "my-app",
   "version": "1.0.0",
-  "workspaces": ["packages/*"],
+  "workspaces": ["packages/*"], // [!code ++]
   "dependencies": {
     "preact": "^10.5.13"
   }
 }
 ```
 
+---
+
 ## Installing dependencies for specific packages
 
 In a monorepo, you can install the dependencies for a subset of packages using the `--filter` flag.
 
-```bash
+```bash terminal icon="terminal"
 # Install dependencies for all workspaces except `pkg-c`
-$ bun install --filter '!pkg-c'
+bun install --filter '!pkg-c'
 
 # Install dependencies for only `pkg-a` in `./packages/pkg-a`
-$ bun install --filter './packages/pkg-a'
+bun install --filter './packages/pkg-a'
 ```
 
-For more information on filtering with `bun install`, refer to [Package Manager > Filtering](https://bun.com/docs/cli/filter#bun-install-and-bun-outdated)
+For more information on filtering with `bun install`, refer to [Package Manager > Filtering](/pm/filter#bun-install-and-bun-outdated)
+
+---
 
 ## Overrides and 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. Refer to [Package manager > Overrides and resolutions](https://bun.com/docs/install/overrides) for complete documentation.
+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. Refer to [Package manager > Overrides and resolutions](/pm/overrides) for complete documentation.
 
-```json-diff#package.json
-  {
-    "name": "my-app",
-    "dependencies": {
-      "foo": "^2.0.0"
-    },
-+   "overrides": {
-+     "bar": "~4.4.0"
-+   }
-  }
+```json package.json file="file-json"
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  },
+  "overrides": {
+    // [!code ++]
+    "bar": "~4.4.0" // [!code ++]
+  } // [!code ++]
+}
 ```
 
+---
+
 ## Global packages
 
 To install a package globally, use the `-g`/`--global` flag. Typically this is used for installing command-line tools.
 
-```bash
-$ bun install --global cowsay # or `bun install -g cowsay`
-$ cowsay "Bun!"
+```bash terminal icon="terminal"
+bun install --global cowsay # or `bun install -g cowsay`
+cowsay "Bun!"
+```
+
+```txt
  ______
 < Bun! >
  ------
@@ -136,49 +162,57 @@ $ cowsay "Bun!"
                 ||     ||
 ```
 
+---
+
 ## Production mode
 
 To install in production mode (i.e. without `devDependencies` or `optionalDependencies`):
 
-```bash
-$ bun install --production
+```bash terminal icon="terminal"
+bun install --production
 ```
 
 For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lock`, Bun will exit with an error. The lockfile will not be updated.
 
-```bash
-$ bun install --frozen-lockfile
+```bash terminal icon="terminal"
+bun install --frozen-lockfile
 ```
 
-For more information on Bun's lockfile `bun.lock`, refer to [Package manager > Lockfile](https://bun.com/docs/install/lockfile).
+For more information on Bun's lockfile `bun.lock`, refer to [Package manager > Lockfile](/pm/lockfile).
+
+---
 
 ## Omitting dependencies
 
 To omit dev, peer, or optional dependencies use the `--omit` flag.
 
-```bash
+```bash terminal icon="terminal"
 # Exclude "devDependencies" from the installation. This will apply to the
 # root package and workspaces if they exist. Transitive dependencies will
 # not have "devDependencies".
-$ bun install --omit dev
+bun install --omit dev
 
 # Install only dependencies from "dependencies"
-$ bun install --omit=dev --omit=peer --omit=optional
+bun install --omit=dev --omit=peer --omit=optional
 ```
 
+---
+
 ## Dry run
 
 To perform a dry run (i.e. don't actually install anything):
 
-```bash
-$ bun install --dry-run
+```bash terminal icon="terminal"
+bun install --dry-run
 ```
 
+---
+
 ## Non-npm dependencies
 
-Bun supports installing dependencies from Git, GitHub, and local or remotely-hosted tarballs. For complete documentation refer to [Package manager > Git, GitHub, and tarball dependencies](https://bun.com/docs/cli/add).
+Bun supports installing dependencies from Git, GitHub, and local or remotely-hosted tarballs. For complete documentation refer to [Package manager > Git, GitHub, and tarball dependencies](/pm/cli/add).
 
-```json#package.json
+```json package.json icon="file-json"
 {
   "dependencies": {
     "dayjs": "git+https://github.com/iamkun/dayjs.git",
@@ -191,6 +225,8 @@ Bun supports installing dependencies from Git, GitHub, and local or remotely-hos
 }
 ```
 
+---
+
 ## Installation strategies
 
 Bun supports two package installation strategies that determine how dependencies are organized in `node_modules`:
@@ -199,40 +235,36 @@ Bun supports two package installation strategies that determine how dependencies
 
 The traditional npm/Yarn approach that flattens dependencies into a shared `node_modules` directory:
 
-```bash
-$ bun install --linker hoisted
+```bash terminal icon="terminal"
+bun install --linker hoisted
 ```
 
 ### Isolated installs
 
 A pnpm-like approach that creates strict dependency isolation to prevent phantom dependencies:
 
-```bash
-$ bun install --linker isolated
+```bash terminal icon="terminal"
+bun install --linker isolated
 ```
 
 Isolated installs create a central package store in `node_modules/.bun/` with symlinks in the top-level `node_modules`. This ensures packages can only access their declared dependencies.
 
-For complete documentation on isolated installs, refer to [Package manager > Isolated installs](https://bun.com/docs/install/isolated).
-
-## Disk efficiency
+For complete documentation on isolated installs, refer to [Package manager > Isolated installs](/pm/isolated-installs).
 
-Bun uses a global cache at `~/.bun/install/cache/` to minimize disk usage. Packages are stored once and linked to `node_modules` using hardlinks (Linux/Windows) or copy-on-write (macOS), so duplicate packages across projects don't consume additional disk space.
-
-For complete documentation refer to [Package manager > Global cache](https://bun.com/docs/install/cache).
+---
 
 ## Minimum release age
 
 To protect against supply chain attacks where malicious packages are quickly published, you can configure a minimum age requirement for npm packages. Package versions published more recently than the specified threshold (in seconds) will be filtered out during installation.
 
-```bash
+```bash terminal icon="terminal"
 # Only install package versions published at least 3 days ago
-$ bun add @types/bun --minimum-release-age 259200 # seconds
+bun add @types/bun --minimum-release-age 259200 # seconds
 ```
 
 You can also configure this in `bunfig.toml`:
 
-```toml
+```toml bunfig.toml icon="settings"
 [install]
 # Only install package versions published at least 3 days ago
 minimumReleaseAge = 259200 # seconds
@@ -251,13 +283,15 @@ When the minimum age filter is active:
   - Exact version requests (like `package@1.1.1`) still respect the age gate but bypass the stability check
 - Versions without a `time` field are treated as passing the age check (npm registry should always provide timestamps)
 
-For more advanced security scanning, including integration with services & custom filtering, see [Package manager > Security Scanner API](https://bun.com/docs/install/security-scanner-api).
+For more advanced security scanning, including integration with services & custom filtering, see [Package manager > Security Scanner API](/pm/security-scanner-api).
+
+---
 
 ## Configuration
 
 The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below.
 
-```toml
+```toml bunfig.toml icon="settings"
 [install]
 
 # whether to install optionalDependencies
@@ -285,19 +319,23 @@ dryRun = false
 concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2
 
 # installation strategy: "hoisted" or "isolated"
-# default: "hoisted"
+# default: "hoisted" (for single-project projects)
+# default: "isolated" (for monorepo projects)
 linker = "hoisted"
 
+
 # minimum age config
 minimumReleaseAge = 259200 # seconds
 minimumReleaseAgeExcludes = ["@types/node", "typescript"]
 ```
 
+---
+
 ## CI/CD
 
 Use the official [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) action to install `bun` in a GitHub Actions pipeline:
 
-```yaml#.github/workflows/release.yml
+```yaml .github/workflows/release.yml icon="file-code"
 name: bun-types
 jobs:
   build:
@@ -316,15 +354,15 @@ jobs:
 
 For CI/CD environments that want to enforce reproducible builds, use `bun ci` to fail the build if the package.json is out of sync with the lockfile:
 
-```bash
-$ bun ci
+```bash terminal icon="terminal"
+bun ci
 ```
 
 This is equivalent to `bun install --frozen-lockfile`. It installs exact versions from `bun.lock` and fails if `package.json` doesn't match the lockfile. To use `bun ci` or `bun install --frozen-lockfile`, you must commit `bun.lock` to version control.
 
 And instead of running `bun install`, run `bun ci`.
 
-```yaml#.github/workflows/release.yml
+```yaml .github/workflows/release.yml icon="file-code"
 name: bun-types
 jobs:
   build:
@@ -341,4 +379,93 @@ jobs:
         run: bun run build
 ```
 
-{% bunCLIUsage command="install" /%}
+## pnpm migration
+
+Bun automatically migrates projects from pnpm to bun. When a `pnpm-lock.yaml` file is detected and no `bun.lock` file exists, Bun will automatically migrate the lockfile to `bun.lock` during installation. The original `pnpm-lock.yaml` file remains unmodified.
+
+```bash terminal icon="terminal"
+bun install
+```
+
+**Note**: Migration only runs when `bun.lock` is absent. There is currently no opt-out flag for pnpm migration.
+
+The migration process handles:
+
+### Lockfile Migration
+
+- Converts `pnpm-lock.yaml` to `bun.lock` format
+- Preserves package versions and resolution information
+- Maintains dependency relationships and peer dependencies
+- Handles patched dependencies with integrity hashes
+
+### Workspace Configuration
+
+When a `pnpm-workspace.yaml` file exists, Bun migrates workspace settings to your root `package.json`:
+
+```yaml pnpm-workspace.yaml icon="file-code"
+packages:
+  - "apps/*"
+  - "packages/*"
+
+catalog:
+  react: ^18.0.0
+  typescript: ^5.0.0
+
+catalogs:
+  build:
+    webpack: ^5.0.0
+    babel: ^7.0.0
+```
+
+The workspace packages list and catalogs are moved to the `workspaces` field in `package.json`:
+
+```json package.json icon="file-json"
+{
+  "workspaces": {
+    "packages": ["apps/*", "packages/*"],
+    "catalog": {
+      "react": "^18.0.0",
+      "typescript": "^5.0.0"
+    },
+    "catalogs": {
+      "build": {
+        "webpack": "^5.0.0",
+        "babel": "^7.0.0"
+      }
+    }
+  }
+}
+```
+
+### Catalog Dependencies
+
+Dependencies using pnpm's `catalog:` protocol are preserved:
+
+```json package.json icon="file-json"
+{
+  "dependencies": {
+    "react": "catalog:",
+    "webpack": "catalog:build"
+  }
+}
+```
+
+### Configuration Migration
+
+The following pnpm configuration is migrated from both `pnpm-lock.yaml` and `pnpm-workspace.yaml`:
+
+- **Overrides**: Moved from `pnpm.overrides` to root-level `overrides` in `package.json`
+- **Patched Dependencies**: Moved from `pnpm.patchedDependencies` to root-level `patchedDependencies` in `package.json`
+- **Workspace Overrides**: Applied from `pnpm-workspace.yaml` to root `package.json`
+
+### Requirements
+
+- Requires pnpm lockfile version 7 or higher
+- Workspace packages must have a `name` field in their `package.json`
+- All catalog entries referenced by dependencies must exist in the catalogs definition
+
+After migration, you can safely remove `pnpm-lock.yaml` and `pnpm-workspace.yaml` files.
+
+---
+
+<Install />

package/docs/{cli/link.md → pm/cli/link.mdx}

@@ -1,13 +1,19 @@
+---
+title: "bun link"
+description: "Link local packages for development"
+---
+
+import Link from "/snippets/cli/link.mdx";
+
 Use `bun link` in a local directory to register the current package as a "linkable" package.
 
-```bash
-$ cd /path/to/cool-pkg
-$ cat package.json
-{
-  "name": "cool-pkg",
-  "version": "1.0.0"
-}
-$ bun link
+```bash terminal icon="terminal"
+cd /path/to/cool-pkg
+cat package.json
+bun link
+```
+
+```txt
 bun link v1.x (7416672e)
 Success! Registered "cool-pkg"
 
@@ -20,21 +26,23 @@ Or add it in dependencies in your package.json file:
 
 This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory.
 
-```bash
-$ cd /path/to/my-app
-$ bun link cool-pkg
+```bash terminal icon="terminal"
+cd /path/to/my-app
+bun link cool-pkg
 ```
 
 In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`:
 
-```json-diff
-  {
-    "name": "my-app",
-    "version": "1.0.0",
-    "dependencies": {
-+     "cool-pkg": "link:cool-pkg"
-    }
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "dependencies": {
+    "cool-pkg": "link:cool-pkg" // [!code ++]
   }
+}
 ```
 
-{% bunCLIUsage command="link" /%}
+---
+
+<Link />