bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/pm/cli/publish.mdx

@@ -0,0 +1,123 @@
+---
+title: "bun publish"
+description: Use `bun publish` to publish a package to the npm registry
+---
+
+import Publish from "/snippets/cli/publish.mdx";
+
+`bun publish` will automatically pack your package into a tarball, strip catalog and workspace protocols from the `package.json` (resolving versions if necessary), and publish to the registry specified in your configuration files. Both `bunfig.toml` and `.npmrc` files are supported.
+
+```sh terminal icon="terminal"
+## Publishing the package from the current working directory
+bun publish
+```
+
+```txt
+bun publish v1.3.1 (ca7428e9)
+
+packed 203B package.json
+packed 224B README.md
+packed 30B index.ts
+packed 0.64KB tsconfig.json
+
+Total files: 4
+Shasum: 79e2b4377b63f4de38dc7ea6e5e9dbee08311a69
+Integrity: sha512-6QSNlDdSwyG/+[...]X6wXHriDWr6fA==
+Unpacked size: 1.1KB
+Packed size: 0.76KB
+Tag: latest
+Access: default
+Registry: http://localhost:4873/
+
+ + publish-1@1.0.0
+```
+
+Alternatively, you can pack and publish your package separately by using `bun pm pack` followed by `bun publish` with the path to the output tarball.
+
+```sh terminal icon="terminal"
+bun pm pack
+...
+bun publish ./package.tgz
+```
+
+<Note>
+  `bun publish` will not run lifecycle scripts (`prepublishOnly/prepack/prepare/postpack/publish/postpublish`) if a
+  tarball path is provided. Scripts will only be run if the package is packed by `bun publish`.
+</Note>
+
+### `--access`
+
+The `--access` flag can be used to set the access level of the package being published. The access level can be one of `public` or `restricted`. Unscoped packages are always public, and attempting to publish an unscoped package with `--access restricted` will result in an error.
+
+```sh terminal icon="terminal"
+bun publish --access public
+```
+
+`--access` can also be set in the `publishConfig` field of your `package.json`.
+
+```json package.json icon="file-json"
+{
+  "publishConfig": {
+    "access": "restricted"
+  }
+}
+```
+
+### `--tag`
+
+Set the tag of the package version being published. By default, the tag is `latest`. The initial version of a package is always given the `latest` tag in addition to the specified tag.
+
+```sh terminal icon="terminal"
+bun publish --tag alpha
+```
+
+`--tag` can also be set in the `publishConfig` field of your `package.json`.
+
+```json package.json icon="file-json"
+{
+  "publishConfig": {
+    "tag": "next"
+  }
+}
+```
+
+### `--dry-run`
+
+The `--dry-run` flag can be used to simulate the publish process without actually publishing the package. This is useful for verifying the contents of the published package without actually publishing the package.
+
+```sh terminal icon="terminal"
+bun publish --dry-run
+```
+
+### `--gzip-level`
+
+Specify the level of gzip compression to use when packing the package. Only applies to `bun publish` without a tarball path argument. Values range from `0` to `9` (default is `9`).
+
+### `--auth-type`
+
+If you have 2FA enabled for your npm account, `bun publish` will prompt you for a one-time password. This can be done through a browser or the CLI. The `--auth-type` flag can be used to tell the npm registry which method you prefer. The possible values are `web` and `legacy`, with `web` being the default.
+
+```sh terminal icon="terminal"
+bun publish --auth-type legacy
+...
+This operation requires a one-time password.
+Enter OTP: 123456
+...
+```
+
+### `--otp`
+
+Provide a one-time password directly to the CLI. If the password is valid, this will skip the extra prompt for a one-time password before publishing. Example usage:
+
+```sh terminal icon="terminal"
+bun publish --otp 123456
+```
+
+<Note>
+  `bun publish` respects the `NPM_CONFIG_TOKEN` environment variable which can be used when publishing in github actions
+  or automated workflows.
+</Note>
+
+---
+
+<Publish />

package/docs/pm/cli/remove.mdx

@@ -0,0 +1,16 @@
+---
+title: "bun remove"
+description: "Remove dependencies from your project"
+---
+
+import Remove from "/snippets/cli/remove.mdx";
+
+## Basic Usage
+
+```bash terminal icon="terminal"
+bun remove ts-node
+```
+
+---
+
+<Remove />

package/docs/pm/cli/update.mdx

@@ -0,0 +1,140 @@
+---
+title: "bun update"
+description: "Update dependencies to latest versions"
+---
+
+import Update from "/snippets/cli/update.mdx";
+
+<Note>To upgrade your Bun CLI version, see [`bun upgrade`](/installation#upgrading).</Note>
+
+To update all dependencies to the latest version:
+
+```sh terminal icon="terminal"
+bun update
+```
+
+To update a specific dependency to the latest version:
+
+```sh terminal icon="terminal"
+bun update [package]
+```
+
+## `--interactive`
+
+For a more controlled update experience, use the `--interactive` flag to select which packages to update:
+
+```sh terminal icon="terminal"
+bun update --interactive
+bun update -i
+```
+
+This launches an interactive terminal interface that shows all outdated packages with their current and target versions. You can then select which packages to update.
+
+### Interactive Interface
+
+The interface displays packages grouped by dependency type:
+
+```txt
+? Select packages to update - Space to toggle, Enter to confirm, a to select all, n to select none, i to invert, l to toggle latest
+
+  dependencies                Current  Target   Latest
+    □ react                   17.0.2   18.2.0   18.3.1
+    □ lodash                  4.17.20  4.17.21  4.17.21
+
+  devDependencies             Current  Target   Latest
+    □ typescript              4.8.0    5.0.0    5.3.3
+    □ @types/node             16.11.7  18.0.0   20.11.5
+
+  optionalDependencies        Current  Target   Latest
+    □ some-optional-package   1.0.0    1.1.0    1.2.0
+```
+
+**Sections:**
+
+- Packages are grouped under section headers: `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`
+- Each section shows column headers aligned with the package data
+
+**Columns:**
+
+- **Package**: Package name (may have suffix like ` dev`, ` peer`, ` optional` for clarity)
+- **Current**: Currently installed version
+- **Target**: Version that would be installed (respects semver constraints)
+- **Latest**: Latest available version
+
+### Keyboard Controls
+
+**Selection:**
+
+- **Space**: Toggle package selection
+- **Enter**: Confirm selections and update
+- **a/A**: Select all packages
+- **n/N**: Select none
+- **i/I**: Invert selection
+
+**Navigation:**
+
+- **↑/↓ Arrow keys** or **j/k**: Move cursor
+- **l/L**: Toggle between target and latest version for current package
+
+**Exit:**
+
+- **Ctrl+C** or **Ctrl+D**: Cancel without updating
+
+### Visual Indicators
+
+- **☑** Selected packages (will be updated)
+- **□** Unselected packages
+- **>** Current cursor position
+- **Colors**: Red (major), yellow (minor), green (patch) version changes
+- **Underlined**: Currently selected update target
+
+### Package Grouping
+
+Packages are organized in sections by dependency type:
+
+- **dependencies** - Regular runtime dependencies
+- **devDependencies** - Development dependencies
+- **peerDependencies** - Peer dependencies
+- **optionalDependencies** - Optional dependencies
+
+Within each section, individual packages may have additional suffixes (` dev`, ` peer`, ` optional`) for extra clarity.
+
+## `--recursive`
+
+Use the `--recursive` flag with `--interactive` to update dependencies across all workspaces in a monorepo:
+
+```sh terminal icon="terminal"
+bun update --interactive --recursive
+bun update -i -r
+```
+
+This displays an additional "Workspace" column showing which workspace each dependency belongs to.
+
+## `--latest`
+
+By default, `bun update` will update to the latest version of a dependency that satisfies the version range specified in your `package.json`.
+
+To update to the latest version, regardless of if it's compatible with the current version range, use the `--latest` flag:
+
+```sh terminal icon="terminal"
+bun update --latest
+```
+
+In interactive mode, you can toggle individual packages between their target version (respecting semver) and latest version using the **l** key.
+
+For example, with the following `package.json`:
+
+```json package.json icon="file-json"
+{
+  "dependencies": {
+    "react": "^17.0.2"
+  }
+}
+```
+
+- `bun update` would update to a version that matches `17.x`.
+- `bun update --latest` would update to a version that matches `18.x` or later.
+
+---
+
+<Update />

package/docs/pm/cli/why.mdx

@@ -0,0 +1,84 @@
+---
+title: "bun why"
+description: "Explain why a package is installed"
+---
+
+The `bun why` command explains why a package is installed in your project by showing the dependency chain that led to its installation.
+
+## Usage
+
+```bash terminal icon="terminal"
+bun why <package>
+```
+
+## Arguments
+
+- `<package>`: The name of the package to explain. Supports glob patterns like `@org/*` or `*-lodash`.
+
+## Options
+
+- `--top`: Show only the top-level dependencies instead of the complete dependency tree.
+- `--depth <number>`: Maximum depth of the dependency tree to display.
+
+## Examples
+
+Check why a specific package is installed:
+
+```bash terminal icon="terminal"
+bun why react
+```
+
+```txt
+react@18.2.0
+  └─ my-app@1.0.0 (requires ^18.0.0)
+```
+
+Check why all packages with a specific pattern are installed:
+
+```bash terminal icon="terminal"
+bun why "@types/*"
+```
+
+```txt
+@types/react@18.2.15
+  └─ dev my-app@1.0.0 (requires ^18.0.0)
+
+@types/react-dom@18.2.7
+  └─ dev my-app@1.0.0 (requires ^18.0.0)
+```
+
+Show only top-level dependencies:
+
+```bash terminal icon="terminal"
+bun why express --top
+```
+
+```txt
+express@4.18.2
+  └─ my-app@1.0.0 (requires ^4.18.2)
+```
+
+Limit the dependency tree depth:
+
+```bash terminal icon="terminal"
+bun why express --depth 2
+```
+
+```txt
+express@4.18.2
+  └─ express-pollyfill@1.20.1 (requires ^4.18.2)
+     └─ body-parser@1.20.1 (requires ^1.20.1)
+     └─ accepts@1.3.8 (requires ^1.3.8)
+        └─ (deeper dependencies hidden)
+```
+
+## Understanding the Output
+
+The output shows:
+
+- The package name and version being queried
+- The dependency chain that led to its installation
+- The type of dependency (dev, peer, optional, or production)
+- The version requirement specified in each package's dependencies
+
+For nested dependencies, the command shows the complete dependency tree by default, with indentation indicating the relationship hierarchy.

package/docs/pm/filter.mdx

@@ -0,0 +1,102 @@
+---
+title: "bun --filter"
+description: "Select packages by pattern in a monorepo using the --filter flag"
+---
+
+The `--filter` (or `-F`) flag is used for selecting packages by pattern in a monorepo. Patterns can be used to match package names or package paths, with full glob syntax support.
+
+Currently `--filter` is supported by `bun install` and `bun outdated`, and can also be used to run scripts for multiple packages at once.
+
+---
+
+## Matching
+
+### Package Name `--filter <pattern>`
+
+Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkg-a`, `pkg-b` and `other`, you can match all packages with `*`, only `pkg-a` and `pkg-b` with `pkg*`, and a specific package by providing the full name of the package.
+
+### Package Path `--filter ./<glob>`
+
+Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `packages/foo`, use `--filter ./packages/foo`.
+
+---
+
+## `bun install` and `bun outdated`
+
+Both `bun install` and `bun outdated` support the `--filter` flag.
+
+`bun install` by default will install dependencies for all packages in the monorepo. To install dependencies for specific packages, use `--filter`.
+
+Given a monorepo with workspaces `pkg-a`, `pkg-b`, and `pkg-c` under `./packages`:
+
+```bash terminal icon="terminal"
+# Install dependencies for all workspaces except `pkg-c`
+bun install --filter '!pkg-c'
+
+# Install dependencies for packages in `./packages` (`pkg-a`, `pkg-b`, `pkg-c`)
+bun install --filter './packages/*'
+
+# Save as above, but exclude the root package.json
+bun install --filter '!./' --filter './packages/*'
+```
+
+Similarly, `bun outdated` will display outdated dependencies for all packages in the monorepo, and `--filter` can be used to restrict the command to a subset of the packages:
+
+```bash terminal icon="terminal"
+# Display outdated dependencies for workspaces starting with `pkg-`
+bun outdated --filter 'pkg-*'
+
+# Display outdated dependencies for only the root package.json
+bun outdated --filter './'
+```
+
+For more information on both these commands, see [`bun install`](/pm/cli/install) and [`bun outdated`](/pm/cli/outdated).
+
+---
+
+## Running scripts with `--filter`
+
+Use the `--filter` flag to execute scripts in multiple packages at once:
+
+```bash terminal icon="terminal"
+bun --filter <pattern> <script>
+```
+
+Say you have a monorepo with two packages: `packages/api` and `packages/frontend`, both with a `dev` script that will start a local development server. Normally, you would have to open two separate terminal tabs, cd into each package directory, and run `bun dev`:
+
+```bash terminal icon="terminal"
+cd packages/api
+bun dev
+
+# in another terminal
+cd packages/frontend
+bun dev
+```
+
+Using `--filter`, you can run the `dev` script in both packages at once:
+
+```bash terminal icon="terminal"
+bun --filter '*' dev
+```
+
+Both commands will be run in parallel, and you will see a nice terminal UI showing their respective outputs:
+
+<Frame>![Terminal Output](https://github.com/oven-sh/bun/assets/48869301/2a103e42-9921-4c33-948f-a1ad6e6bac71)</Frame>
+
+### Running scripts in workspaces
+
+Filters respect your [workspace configuration](/pm/workspaces): If you have a `package.json` file that specifies which packages are part of the workspace,
+`--filter` will be restricted to only these packages. Also, in a workspace you can use `--filter` to run scripts in packages that are located anywhere in the workspace:
+
+```bash terminal icon="terminal"
+# Packages
+# src/foo
+# src/bar
+
+# in src/bar: runs myscript in src/foo, no need to cd!
+bun run --filter foo myscript
+```
+
+### Dependency Order
+
+Bun will respect package dependency order when running scripts. Say you have a package `foo` that depends on another package `bar` in your workspace, and both packages have a `build` script. When you run `bun --filter '*' build`, you will notice that `foo` will only start running once `bar` is done.

package/docs/pm/global-cache.mdx

@@ -0,0 +1,72 @@
+---
+title: "Global cache"
+description: "How Bun stores and manages packages in its global cache"
+---
+
+All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`, or the path defined by the environment variable `BUN_INSTALL_CACHE_DIR`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached.
+
+<Accordion title="Configuring cache behavior">
+
+```toml bunfig.toml icon="settings"
+[install.cache]
+# the directory to use for the cache
+dir = "~/.bun/install/cache"
+
+# when true, don't load from the global cache.
+# Bun may still write to node_modules/.cache
+disable = false
+
+# when true, always resolve the latest versions from the registry
+disableManifest = false
+```
+
+</Accordion>
+
+---
+
+## Minimizing re-downloads
+
+Bun strives to avoid re-downloading packages multiple times. When installing a package, if the cache already contains a version in the range specified by `package.json`, Bun will use the cached package instead of downloading it again.
+
+<Accordion title="Installation details">
+If the semver version has pre-release suffix (`1.0.0-beta.0`) or a build suffix (`1.0.0+20220101`), it is replaced with a hash of that value instead, to reduce the chances of errors associated with long file paths.
+
+When the `node_modules` folder exists, before installing, Bun checks that `node_modules` contains all expected packages with appropriate versions. If so `bun install` completes. Bun uses a custom JSON parser which stops parsing as soon as it finds `"name"` and `"version"`.
+
+If a package is missing or has a version incompatible with the `package.json`, Bun checks for a compatible module in the cache. If found, it is installed into `node_modules`. Otherwise, the package will be downloaded from the registry then installed.
+
+</Accordion>
+
+---
+
+## Fast copying
+
+Once a package is downloaded into the cache, Bun still needs to copy those files into `node_modules`. Bun uses the fastest syscalls available to perform this task. On Linux, it uses hardlinks; on macOS, it uses `clonefile`.
+
+---
+
+## Saving disk space
+
+Since Bun uses hardlinks to "copy" a module into a project's `node_modules` directory on Linux and Windows, the contents of the package only exist in a single location on disk, greatly reducing the amount of disk space dedicated to `node_modules`.
+
+This benefit also applies to macOS, but there are exceptions. It uses `clonefile` which is copy-on-write, meaning it will not occupy disk space, but it will count towards drive's limit. This behavior is useful if something attempts to patch `node_modules/*`, so it's impossible to affect other installations.
+
+<Accordion title="Installation strategies">
+This behavior is configurable with the `--backend` flag, which is respected by all of Bun's package management commands.
+
+- **`hardlink`**: Default on Linux and Windows.
+- **`clonefile`** Default on macOS.
+- **`clonefile_each_dir`**: Similar to `clonefile`, except it clones each file individually per directory. It is only available on macOS and tends to perform slower than `clonefile`.
+- **`copyfile`**: The fallback used when any of the above fail. It is the slowest option. On macOS, it uses `fcopyfile()`; on Linux it uses `copy_file_range()`.
+- **`symlink`**: Currently used only `file:` (and eventually `link:`) dependencies. To prevent infinite loops, it skips symlinking the `node_modules` folder.
+
+If you install with `--backend=symlink`, Node.js won't resolve node_modules of dependencies unless each dependency has its own `node_modules` folder or you pass `--preserve-symlinks` to `node`. See [Node.js documentation on `--preserve-symlinks`](https://nodejs.org/api/cli.html#--preserve-symlinks).
+
+```bash terminal icon="terminal"
+bun install --backend symlink
+node --preserve-symlinks ./foo.js
+```
+
+Bun's runtime does not currently expose an equivalent of `--preserve-symlinks`.
+
+</Accordion>