bun-types 1.3.2-canary.20251106T140813 → 1.3.2-canary.20251108T140624

package/docs/guides/install/from-npm-install-to-bun-install.mdx

@@ -0,0 +1,230 @@
+---
+title: Migrate from npm install to bun install
+sidebarTitle: Migrate from npm to bun
+mode: center
+---
+
+`bun install` is a Node.js compatible npm client designed to be an incredibly fast successor to npm.
+
+We've put a lot of work into making sure that the migration path from `npm install` to `bun install` is as easy as running `bun install` instead of `npm install`.
+
+- **Designed for Node.js & Bun**: `bun install` installs a Node.js compatible `node_modules` folder. You can use it in place of `npm install` for Node.js projects without any code changes and without using Bun's runtime.
+- **Automatically converts `package-lock.json`** to bun's `bun.lock` lockfile format, preserving your existing resolved dependency versions without any manual work on your part. You can secretly use `bun install` in place of `npm install` at work without anyone noticing.
+- **`.npmrc` compatible**: bun install reads npm registry configuration from npm's `.npmrc`, so you can use the same configuration for both npm and Bun.
+- **Hardlinks**: On Windows and Linux, `bun install` uses hardlinks to conserve disk space and install times.
+
+```bash terminal icon="terminal"
+# It only takes one command to migrate
+bun i
+
+# To add dependencies:
+bun i @types/bun
+
+# To add devDependencies:
+bun i -d @types/bun
+
+# To remove a dependency:
+bun rm @types/bun
+```
+
+---
+
+## Run package.json scripts faster
+
+Run scripts from package.json, executables from `node_modules/.bin` (sort of like `npx`), and JavaScript/TypeScript files (just like `node`) - all from a single simple command.
+
+| NPM                | Bun              |
+| ------------------ | ---------------- |
+| `npm run <script>` | `bun <script>`   |
+| `npm exec <bin>`   | `bun <bin>`      |
+| `node <file>`      | `bun <file>`     |
+| `npx <package>`    | `bunx <package>` |
+
+When you use `bun run <executable>`, it will choose the locally-installed executable
+
+```sh terminal icon="terminal"
+# Run a package.json script:
+bun my-script
+bun run my-script
+
+# Run an executable in node_modules/.bin:
+bun my-executable # such as tsc, esbuild, etc.
+bun run my-executable
+
+# Run a JavaScript/TypeScript file:
+bun ./index.ts
+```
+
+---
+
+## Workspaces? Yes.
+
+`bun install` supports workspaces similarly to npm, with more features.
+
+In package.json, you can set `"workspaces"` to an array of relative paths.
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "workspaces": ["packages/*", "apps/*"]
+}
+```
+
+---
+
+### Filter scripts by workspace name
+
+In Bun, the `--filter` flag accepts a glob pattern, and will run the command concurrently for all workspace packages with a `name` that matches the pattern, respecting dependency order.
+
+```sh terminal icon="terminal"
+bun --filter 'lib-*' my-script
+# instead of:
+# npm run --workspace lib-foo --workspace lib-bar my-script
+```
+
+---
+
+## Update dependencies
+
+To update a dependency, you can use `bun update <package>`. This will update the dependency to the latest version that satisfies the semver range specified in package.json.
+
+```sh terminal icon="terminal"
+# Update a single dependency
+bun update @types/bun
+
+# Update all dependencies
+bun update
+
+# Ignore semver, update to the latest version
+bun update @types/bun --latest
+
+# Update a dependency to a specific version
+bun update @types/bun@1.3.1
+
+# Update all dependencies to the latest versions
+bun update --latest
+```
+
+---
+
+### View outdated dependencies
+
+To view outdated dependencies, run `bun outdated`. This is like `npm outdated` but with more compact output.
+
+```sh terminal icon="terminal"
+bun outdated
+```
+
+```txt
+┌────────────────────────────────────────┬─────────┬────────┬────────┐
+│ Package                                │ Current │ Update │ Latest │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @types/bun (dev)                       │ 1.1.6   │ 1.1.10 │ 1.1.10 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @types/react (dev)                     │ 18.3.3  │ 18.3.8 │ 18.3.8 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @typescript-eslint/eslint-plugin (dev) │ 7.16.1  │ 7.18.0 │ 8.6.0  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @typescript-eslint/parser (dev)        │ 7.16.1  │ 7.18.0 │ 8.6.0  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @vscode/debugadapter (dev)             │ 1.66.0  │ 1.67.0 │ 1.67.0 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ esbuild (dev)                          │ 0.21.5  │ 0.21.5 │ 0.24.0 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ eslint (dev)                           │ 9.7.0   │ 9.11.0 │ 9.11.0 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ mitata (dev)                           │ 0.1.11  │ 0.1.14 │ 1.0.2  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ prettier-plugin-organize-imports (dev) │ 4.0.0   │ 4.1.0  │ 4.1.0  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ source-map-js (dev)                    │ 1.2.0   │ 1.2.1  │ 1.2.1  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ typescript (dev)                       │ 5.5.3   │ 5.6.2  │ 5.6.2  │
+└────────────────────────────────────────┴─────────┴────────┴────────┘
+```
+
+---
+
+## List installed packages
+
+To list installed packages, you can use `bun pm ls`. This will list all the packages that are installed in the `node_modules` folder using Bun's lockfile as the source of truth. You can pass the `-a` flag to list all installed packages, including transitive dependencies.
+
+```sh terminal icon="terminal"
+# List top-level installed packages:
+bun pm ls
+```
+
+```txt
+my-pkg node_modules (781)
+├── @types/node@20.16.5
+├── @types/react@18.3.8
+├── @types/react-dom@18.3.0
+├── eslint@8.57.1
+├── eslint-config-next@14.2.8
+...
+```
+
+```sh terminal icon="terminal"
+# List all installed packages:
+bun pm ls -a
+```
+
+```txt
+my-pkg node_modules
+├── @alloc/quick-lru@5.2.0
+├── @isaacs/cliui@8.0.2
+│   └── strip-ansi@7.1.0
+│       └── ansi-regex@6.1.0
+├── @jridgewell/gen-mapping@0.3.5
+├── @jridgewell/resolve-uri@3.1.2
+...
+```
+
+---
+
+## Create a package tarball
+
+To create a package tarball, you can use `bun pm pack`. This will create a tarball of the package in the current directory.
+
+```sh terminal icon="terminal"
+# Create a tarball
+bun pm pack
+```
+
+```txt
+Total files: 46
+Shasum: 2ee19b6f0c6b001358449ca0eadead703f326216
+Integrity: sha512-ZV0lzWTEkGAMz[...]Gl4f8lA9sl97g==
+Unpacked size: 0.41MB
+Packed size: 117.50KB
+```
+
+---
+
+## Shebang
+
+If the package references `node` in the `#!/usr/bin/env node` shebang, `bun run` will by default respect it and use the system's `node` executable. You can force it to use Bun's `node` by passing `--bun` to `bun run`.
+
+When you pass `--bun` to `bun run`, we create a symlink to the locally-installed Bun executable named `"node"` in a temporary directory and add that to your `PATH` for the duration of the script's execution.
+
+```sh terminal icon="terminal"
+# Force using Bun's runtime instead of node
+bun --bun my-script
+
+# This also works:
+bun run --bun my-script
+```
+
+---
+
+## Global installs
+
+You can install packages globally using `bun i -g <package>`. This will install into a `.bun/install/global/node_modules` folder inside your home directory by default.
+
+```sh terminal icon="terminal"
+# Install a package globally
+bun i -g eslint
+
+# Run a globally-installed package without the `bun run` prefix
+eslint --init
+```

package/docs/guides/install/git-diff-bun-lockfile.mdx

@@ -0,0 +1,47 @@
+---
+title: Configure git to diff Bun's lockb lockfile
+sidebarTitle: Configure git to diff Bun's lockfile
+mode: center
+---
+
+<Note>
+  Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is human-readable and git-diffable without
+  configuration, at no cost to performance. [**Learn more.**](https://bun.com/docs/install/lockfile#text-based-lockfile)
+</Note>
+
+---
+
+To teach `git` how to generate a human-readable diff of Bun's binary lockfile format (`.lockb`), add the following to your local or global `.gitattributes` file:
+
+```js gitattributes icon="file-code"
+*.lockb binary diff=lockb
+```
+
+---
+
+Then add the following to you local git config with:
+
+```sh terminal icon="terminal"
+git config diff.lockb.textconv bun
+git config diff.lockb.binary true
+```
+
+---
+
+To globally configure git to diff Bun's lockfile, add the following to your global git config with:
+
+```sh terminal icon="terminal"
+git config --global diff.lockb.textconv bun
+git config --global diff.lockb.binary true
+```
+
+---
+
+## How this works
+
+Why this works:
+
+- `textconv` tells git to run bun on the file before diffing
+- `binary` tells git to treat the file as binary (so it doesn't try to diff it line-by-line)
+
+In Bun, you can execute Bun's lockfile (`bun ./bun.lockb`) to generate a human-readable version of the lockfile and `git diff` can then use that to generate a human-readable diff.

package/docs/guides/install/jfrog-artifactory.mdx

@@ -0,0 +1,28 @@
+---
+title: Using bun install with Artifactory
+sidebarTitle: JFrog Artifactory with Bun
+mode: center
+---
+
+[JFrog Artifactory](https://jfrog.com/artifactory/) is a package management system for npm, Docker, Maven, NuGet, Ruby, Helm, and more. It allows you to host your own private npm registry, npm packages, and other types of packages as well.
+
+To use it with `bun install`, add a `bunfig.toml` file to your project with the following contents:
+
+---
+
+### Configure with bunfig.toml
+
+Make sure to replace `MY_SUBDOMAIN` with your JFrog Artifactory subdomain, such as `jarred1234` and MY_TOKEN with your JFrog Artifactory token.
+
+```toml bunfig.toml icon="settings"
+[install.registry]
+url = "https://MY_SUBDOMAIN.jfrog.io/artifactory/api/npm/npm/_auth=MY_TOKEN"
+# Bun v1.0.3+ supports using an environment variable here
+# url = "$NPM_CONFIG_REGISTRY"
+```
+
+---
+
+### Configure with `$NPM_CONFIG_REGISTRY`
+
+Like with npm, you can use the `NPM_CONFIG_REGISTRY` environment variable to configure JFrog Artifactory with bun install.

package/docs/guides/install/npm-alias.mdx

@@ -0,0 +1,25 @@
+---
+title: Install a package under a different name
+sidebarTitle: Install with alias
+mode: center
+---
+
+To install an npm package under an alias:
+
+```sh terminal icon="terminal"
+bun add my-custom-name@npm:zod
+```
+
+---
+
+The `zod` package can now be imported as `my-custom-name`.
+
+```ts index.ts icon="/icons/typescript.svg"
+import { z } from "my-custom-name";
+
+z.string();
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/registry-scope.mdx

@@ -0,0 +1,40 @@
+---
+title: Configure a private registry for an organization scope with bun install
+sidebarTitle: Configure a scoped registry
+mode: center
+---
+
+Private registries can be configured using either [`.npmrc`](https://bun.com/docs/install/npmrc) or [`bunfig.toml`](https://bun.com/docs/runtime/bunfig#install-registry). While both are supported, we recommend using **bunfig.toml** for enhanced flexibility and Bun-specific options.
+
+To configure a registry for a particular npm scope:
+
+```toml bunfig.toml icon="settings"
+[install.scopes]
+# as a string
+"@myorg1" = "https://usertitle:password@registry.myorg.com/"
+
+# as an object with username/password
+# you can reference environment variables
+"@myorg2" = {
+  username = "myusername",
+  password = "$npm_pass",
+  url = "https://registry.myorg.com/"
+}
+
+# as an object with token
+"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
+
+```
+
+---
+
+Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](https://bun.com/docs/runtime/env) for more information.
+
+```toml bunfig.toml icon="settings"
+[install.scopes]
+"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/trusted.mdx

@@ -0,0 +1,50 @@
+---
+title: Add a trusted dependency
+sidebarTitle: Add a trusted dependency
+mode: center
+---
+
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall` and `node-gyp` builds. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
+
+<Note>
+  Bun includes a default allowlist of popular packages containing `postinstall` scripts that are known to be safe. You
+  can see this list [here](https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt).
+</Note>
+
+---
+
+If you are seeing one of the following errors, you are probably trying to use a package that uses `postinstall` to work properly:
+
+- `error: could not determine executable to run for package`
+- `InvalidExe`
+
+---
+
+To allow Bun to execute lifecycle scripts for a specific package, add the package to `trustedDependencies` in your package.json file. You can do this automatically by running the command `bun pm trust <pkg>`.
+
+<Note>
+  Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the
+  dependencies of that dependency!
+</Note>
+
+```json package.json icon="file-json"
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "trustedDependencies": ["my-trusted-package"] // [!code ++]
+}
+```
+
+---
+
+Once this is added, run a fresh install. Bun will re-install your dependencies and properly install
+
+```sh terminal icon="terminal"
+rm -rf node_modules
+rm bun.lock
+bun install
+```
+
+---
+
+See [Docs > Package manager > Trusted dependencies](https://bun.com/docs/install/lifecycle) for complete documentation of trusted dependencies.

package/docs/guides/install/workspaces.mdx

@@ -0,0 +1,70 @@
+---
+title: Configuring a monorepo using workspaces
+sidebarTitle: Workspaces with Bun
+mode: center
+---
+
+Bun's package manager supports npm `"workspaces"`. This allows you to split a codebase into multiple distinct "packages" that live in the same repository, can depend on each other, and (when possible) share a `node_modules` directory.
+
+Clone [this sample project](https://github.com/colinhacks/bun-workspaces) to experiment with workspaces.
+
+---
+
+The root `package.json` should not contain any `"dependencies"`, `"devDependencies"`, etc. Each individual package should be self-contained and declare its own dependencies. Similarly, it's conventional to declare `"private": true` to avoid accidentally publishing the root package to `npm`.
+
+```json package.json icon="file-json"
+{
+  "name": "my-monorepo",
+  "private": true,
+  "workspaces": ["packages/*"]
+}
+```
+
+---
+
+It's common to place all packages in a `packages` directory. The `"workspaces"` field in package.json supports glob patterns, so you can use `packages/*` to indicate that each subdirectory of `packages` should be considered separate _package_ (also known as a workspace).
+
+```txt File Tree icon="folder-tree"
+.
+├── package.json
+├── node_modules
+└── packages
+    ├── stuff-a
+    │   └── package.json
+    └── stuff-b
+        └── package.json
+```
+
+---
+
+To add dependencies between workspaces, use the `"workspace:*"` syntax. Here we're adding `stuff-a` as a dependency of `stuff-b`.
+
+```json packages/stuff-b/package.json icon="file-json"
+{
+  "name": "stuff-b",
+  "dependencies": {
+    "stuff-a": "workspace:*" // [!code ++]
+  }
+}
+```
+
+---
+
+Once added, run `bun install` from the project root to install dependencies for all workspaces.
+
+```sh terminal icon="terminal"
+bun install
+```
+
+---
+
+To add npm dependencies to a particular workspace, just `cd` to the appropriate directory and run `bun add` commands as you would normally. Bun will detect that you are in a workspace and hoist the dependency as needed.
+
+```sh terminal icon="terminal"
+cd packages/stuff-a
+bun add zod
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/yarnlock.mdx

@@ -0,0 +1,50 @@
+---
+title: Generate a yarn-compatible lockfile
+sidebarTitle: Generate a yarn-compatible lockfile
+mode: center
+---
+
+<Note>
+  Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is human-readable and git-diffable without
+  configuration, at no cost to performance. [**Learn more.**](https://bun.com/docs/install/lockfile#text-based-lockfile)
+</Note>
+
+---
+
+Use the `--yarn` flag to generate a Yarn-compatible `yarn.lock` file (in addition to `bun.lock`).
+
+```sh terminal icon="terminal"
+bun install --yarn
+```
+
+---
+
+To set this as the default behavior, add the following to your `bunfig.toml` file.
+
+```toml bunfig.toml icon="settings"
+[install.lockfile]
+print = "yarn"
+```
+
+---
+
+To print a Yarn lockfile to your console without writing it to disk, "run" your `bun.lockb` with `bun`.
+
+```sh terminal icon="terminal"
+bun bun.lockb
+```
+
+```txt
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+# bun ./bun.lockb --hash: 9BFBF11D86084AAB-9418b03ff880c569-390CE6459EACEC9A...
+
+abab@^2.0.6:
+  version "2.0.6"
+  resolved "https://registry.npmjs.org/abab/-/abab-2.0.6.tgz"
+  integrity sha512-j2afSsaIENvHZN2B8GOpF566vZ5WVk5opAiMTvWgaQT8DkbOqsTfvNAvH...
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/process/argv.mdx

@@ -0,0 +1,66 @@
+---
+title: Parse command-line arguments
+sidebarTitle: Parse command-line arguments
+mode: center
+---
+
+The _argument vector_ is the list of arguments passed to the program when it is run. It is available as `Bun.argv`.
+
+```ts cli.ts icon="/icons/typescript.svg"
+console.log(Bun.argv);
+```
+
+---
+
+Running this file with arguments results in the following:
+
+```sh terminal icon="terminal"
+bun run cli.ts --flag1 --flag2 value
+```
+
+```txt
+[ '/path/to/bun', '/path/to/cli.ts', '--flag1', '--flag2', 'value' ]
+```
+
+---
+
+To parse `argv` into a more useful format, `util.parseArgs` would be helpful.
+
+Example:
+
+```ts cli.ts icon="/icons/typescript.svg"
+import { parseArgs } from "util";
+
+const { values, positionals } = parseArgs({
+  args: Bun.argv,
+  options: {
+    flag1: {
+      type: "boolean",
+    },
+    flag2: {
+      type: "string",
+    },
+  },
+  strict: true,
+  allowPositionals: true,
+});
+
+console.log(values);
+console.log(positionals);
+```
+
+---
+
+then it outputs
+
+```sh terminal icon="terminal"
+bun run cli.ts --flag1 --flag2 value
+```
+
+```txt
+{
+  flag1: true,
+  flag2: "value",
+}
+[ "/path/to/bun", "/path/to/cli.ts" ]
+```

package/docs/guides/process/ctrl-c.mdx

@@ -0,0 +1,18 @@
+---
+title: Listen for CTRL+C
+sidebarTitle: Listen for CTRL+C
+mode: center
+---
+
+The `ctrl+c` shortcut sends an _interrupt signal_ to the running process. This signal can be intercepted by listening for the `SIGINT` event. If you want to close the process, you must explicitly call `process.exit()`.
+
+```ts process.ts icon="/icons/typescript.svg"
+process.on("SIGINT", () => {
+  console.log("Ctrl-C was pressed");
+  process.exit();
+});
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.