bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/install/index.md

@@ -1,248 +0,0 @@
-The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`. It's designed for Node.js compatibility; use it in any Bun or Node.js project.
-
-{% callout %}
-
-**⚡️ 80x faster** — Switch from `npm install` to `bun install` in any Node.js project to make your installations up to 80x faster.
-
-{% image src="https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png" height="200" /%}
-
-{% /callout %}
-
-{% details summary="For Linux users" %}
-The minimum Linux Kernel version is 5.1. If you're on Linux kernel 5.1 - 5.5, `bun install` should still 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
-# If this returns a version >= 5.6, you don't need to do anything
-uname -r
-
-# Install the official Ubuntu hardware enablement kernel
-sudo apt install --install-recommends linux-generic-hwe-20.04
-```
-
-{% /details %}
-
-## Manage dependencies
-
-### `bun install`
-
-To install all dependencies of a project:
-
-```bash
-$ bun install
-```
-
-On Linux, `bun install` tends to install packages 20-100x faster than `npm install`. On macOS, it's more like 4-80x.
-
-![package install benchmark](https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png)
-
-Running `bun install` will:
-
-- **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun will install `peerDependencies` by default.
-- **Run** your project's `{pre|post}install` 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.
-
-To install in production mode (i.e. without `devDependencies`):
-
-```bash
-$ bun install --production
-```
-
-To install dependencies without allowing changes to lockfile (useful on CI):
-
-```bash
-$ bun install --frozen-lockfile
-```
-
-To exclude dependency types from installing, use `--omit` with `dev`, `optional`, or `peer`:
-
-```bash
-# Disable devDependencies and optionalDependencies
-$ bun install --omit=dev --omit=optional
-```
-
-To perform a dry run (i.e. don't actually install anything or update the lockfile):
-
-```bash
-$ bun install --dry-run
-```
-
-To generate a lockfile without install packages:
-
-```bash
-$ bun install --lockfile-only
-```
-
-To modify logging verbosity:
-
-```bash
-$ bun install --verbose # debug logging
-$ bun install --silent  # no logging
-```
-
-To use isolated installs instead of the default hoisted strategy:
-
-```bash
-$ bun install --linker isolated
-```
-
-Isolated installs create strict dependency isolation similar to pnpm, preventing phantom dependencies and ensuring more deterministic builds. For complete documentation, see [Isolated installs](https://bun.com/docs/install/isolated).
-
-To protect against supply chain attacks, set a minimum age (in seconds) for package versions:
-
-```bash
-$ bun install --minimum-release-age 259200 # 3 days
-```
-
-{% details summary="Configuring behavior" %}
-The default behavior of `bun install` can be configured in `bunfig.toml`:
-
-```toml
-[install]
-
-# whether to install optionalDependencies
-optional = true
-
-# whether to install devDependencies
-dev = true
-
-# whether to install peerDependencies
-peer = true
-
-# equivalent to `--production` flag
-production = false
-
-# equivalent to `--save-text-lockfile` flag
-saveTextLockfile = false
-
-# equivalent to `--frozen-lockfile` flag
-frozenLockfile = false
-
-# equivalent to `--dry-run` flag
-dryRun = false
-
-# equivalent to `--concurrent-scripts` flag
-concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2
-
-# installation strategy: "hoisted" or "isolated"
-# default: "hoisted"
-linker = "hoisted"
-
-# minimum package age in seconds (protects against supply chain attacks)
-minimumReleaseAge = 259200 # 3 days
-
-# exclude packages from age requirement
-minimumReleaseAgeExcludes = ["@types/node", "typescript"]
-```
-
-{% /details %}
-
-### `bun add`
-
-To add a particular package:
-
-```bash
-$ bun add preact
-```
-
-To specify a version, version range, or tag:
-
-```bash
-$ bun add zod@3.20.0
-$ bun add zod@^3.0.0
-$ bun add zod@latest
-```
-
-To add a package as a dev dependency (`"devDependencies"`):
-
-```bash
-$ bun add --dev @types/react
-$ bun add -d @types/react
-```
-
-To add a package as an optional dependency (`"optionalDependencies"`):
-
-```bash
-$ bun add --optional lodash
-```
-
-To add a package as a peer dependency (`"peerDependencies"`):
-
-```bash
-$ bun add --peer @types/bun
-```
-
-To install a package globally:
-
-```bash
-$ bun add --global cowsay # or `bun add -g cowsay`
-$ cowsay "Bun!"
- ______
-< Bun! >
- ------
-        \   ^__^
-         \  (oo)\_______
-            (__)\       )\/\
-                ||----w |
-                ||     ||
-```
-
-{% details summary="Configuring global installation behavior" %}
-
-```toml
-[install]
-# where `bun install --global` installs packages
-globalDir = "~/.bun/install/global"
-
-# where globally-installed package bins are linked
-globalBinDir = "~/.bun/bin"
-```
-
-{% /details %}
-To view a complete list of options for a given command:
-
-```bash
-$ bun add --help
-```
-
-### `bun remove`
-
-To remove a dependency:
-
-```bash
-$ bun remove preact
-```
-
-## Git dependencies
-
-To add a dependency from a git repository:
-
-```bash
-$ bun install git@github.com:moment/moment.git
-```
-
-Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more.
-
-```json
-{
-  "dependencies": {
-    "dayjs": "git+https://github.com/iamkun/dayjs.git",
-    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
-    "moment": "git@github.com:moment/moment.git",
-    "zod": "github:colinhacks/zod"
-  }
-}
-```
-
-## Tarball dependencies
-
-A package name can correspond to a publicly hosted `.tgz` file. During `bun install`, Bun will download and install the package from the specified tarball URL, rather than from the package registry.
-
-```json#package.json
-{
-  "dependencies": {
-    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
-  }
-}
-```

package/docs/install/isolated.md

@@ -1,197 +0,0 @@
-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.
-
-## 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
-# 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`:
-
-```toml
-[install]
-linker = "isolated"
-```
-
-### Default behavior
-
-- **Workspaces**: Bun uses **isolated** installs by default to prevent hoisting-related bugs
-- **Single projects**: Bun uses **hoisted** installs by default
-
-To override the default, use `--linker hoisted` or `--linker isolated`, or set it in your configuration file.
-
-## How isolated installs work
-
-### Directory structure
-
-Instead of hoisting dependencies, isolated installs create a two-tier structure:
-
-```
-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
-# 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
-$ 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
-   $ 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
-# 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
-# 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
-
-**Isolated installs are the default for workspaces.** You may want to explicitly enable them for single projects when:
-
-- Strict dependency management is required
-- Preventing phantom dependencies is important
-- Building libraries that need deterministic dependencies
-
-**Switch to hoisted installs (including for workspaces) 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](https://bun.com/docs/install/workspaces) — Monorepo workspace management
-- [Package manager > Lockfile](https://bun.com/docs/install/lockfile) — Understanding Bun's lockfile format
-- [CLI > install](https://bun.com/docs/cli/install) — Complete `bun install` command reference

package/docs/install/lifecycle.md

@@ -1,46 +0,0 @@
-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
-{
-  "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-diff
-  {
-    "name": "my-app",
-    "version": "1.0.0",
-+   "trustedDependencies": ["node-sass"]
-  }
-```
-
-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
-```

package/docs/install/lockfile.md

@@ -1,58 +0,0 @@
-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
-$ bun install --lockfile-only
-```
-
-{% callout %}
-**Note** - using `--lockfile-only` will still populate the global install cache with registry metadata and git/tarball dependencies.
-{% /callout %}
-
-#### Can I opt out?
-
-To install without creating a lockfile:
-
-```bash
-$ bun install --no-save
-```
-
-To install a Yarn lockfile _in addition_ to `bun.lock`.
-
-{% codetabs %}
-
-```bash#CLI flag
-$ bun install --yarn
-```
-
-```toml#bunfig.toml
-[install.lockfile]
-# whether to save a non-Bun lockfile alongside bun.lock
-# only "yarn" is supported
-print = "yarn"
-```
-
-{% /codetabs %}
-
-#### 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/install/npmrc.md

@@ -1,105 +0,0 @@
-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.
-
-{% callout %}
-
-**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.
-
-{% /callout %}
-
-## Supported options
-
-### `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
-registry=http://localhost:4873/
-```
-
-The equivalent `bunfig.toml` option is [`install.registry`](https://bun.com/docs/runtime/bunfig#install-registry):
-
-```toml
-install.registry = "http://localhost:4873/"
-```
-
-### `@<scope>:registry`: Set the registry for a specific scope
-
-Allows you to set the registry for a specific scope:
-
-```ini
-@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):
-
-```toml
-[install.scopes]
-myorg = "http://localhost:4873/"
-```
-
-### `//<registry_url>/:<key>=<value>`: Configure options for a specific registry
-
-Allows you to set options for a specific registry:
-
-```ini
-# 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`](https://bun.com/docs/runtime/bunfig#install-registry):
-
-```toml
-[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
-link-workspace-packages=true
-```
-
-The equivalent `bunfig.toml` option is [`install.linkWorkspacePackages`](https://bun.com/docs/runtime/bunfig#install-linkworkspacepackages):
-
-```toml
-[install]
-linkWorkspacePackages = true
-```
-
-### `save-exact`: Save exact versions
-
-Always saves exact versions without the `^` prefix:
-
-```ini
-save-exact=true
-```
-
-The equivalent `bunfig.toml` option is [`install.exact`](https://bun.com/docs/runtime/bunfig#install-exact):
-
-```toml
-[install]
-exact = true
-```