bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/runtime/{bunfig.md → bunfig.mdx}

@@ -1,3 +1,8 @@
+---
+title: "bunfig.toml"
+description: "Configure Bun's behavior using its configuration file bunfig.toml"
+---
+
 Bun's behavior can be configured using its configuration file, `bunfig.toml`.
 
 In general, Bun relies on pre-existing configuration files like `package.json` and `tsconfig.json` to configure its behavior. `bunfig.toml` is only necessary for configuring Bun-specific things. This file is optional, and Bun will work out of the box without it.
@@ -21,7 +26,7 @@ Bun's runtime behavior is configured using top-level fields in the `bunfig.toml`
 
 An array of scripts/plugins to execute before running a file or script.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 # scripts to run before `bun run`-ing a file or script
 # register plugins by adding them to this list
 preload = ["./preload.ts"]
@@ -31,7 +36,7 @@ preload = ["./preload.ts"]
 
 Configure how Bun handles JSX. You can also set these fields in the `compilerOptions` of your `tsconfig.json`, but they are supported here as well for non-TypeScript projects.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 jsx = "react"
 jsxFactory = "h"
 jsxFragment = "Fragment"
@@ -40,16 +45,16 @@ jsxImportSource = "react"
 
 Refer to the tsconfig docs for more information on these fields.
 
-- [jsx](https://www.typescriptlang.org/tsconfig#jsx)
-- [jsxFactory](https://www.typescriptlang.org/tsconfig#jsxFactory)
-- [jsxFragment](https://www.typescriptlang.org/tsconfig#jsxFragment)
-- [jsxImportSource](https://www.typescriptlang.org/tsconfig#jsxImportSource)
+- [`jsx`](https://www.typescriptlang.org/tsconfig#jsx)
+- [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
+- [`jsxFragment`](https://www.typescriptlang.org/tsconfig#jsxFragment)
+- [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource)
 
 ### `smol`
 
 Enable `smol` mode. This reduces memory usage at the cost of performance.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 # Reduce memory usage at the cost of performance
 smol = true
 ```
@@ -58,7 +63,7 @@ smol = true
 
 Set the log level. This can be one of `"debug"`, `"warn"`, or `"error"`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 logLevel = "debug" # "debug" | "warn" | "error"
 ```
 
@@ -66,7 +71,7 @@ logLevel = "debug" # "debug" | "warn" | "error"
 
 The `define` field allows you to replace certain global identifiers with constant expressions. Bun will replace any usage of the identifier with the expression. The expression should be a JSON string.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [define]
 # Replace any usage of "process.env.bagel" with the string `lox`.
 # The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS.
@@ -78,7 +83,7 @@ The `define` field allows you to replace certain global identifiers with constan
 
 Configure how Bun maps file extensions to loaders. This is useful for loading files that aren't natively supported by Bun.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [loader]
 # when a .bagel file is imported, treat it like a tsx file
 ".bagel" = "tsx"
@@ -94,7 +99,6 @@ Bun supports the following loaders:
 - `file`
 - `json`
 - `toml`
-- `yaml`
 - `wasm`
 - `napi`
 - `base64`
@@ -105,7 +109,7 @@ Bun supports the following loaders:
 
 The `telemetry` field permit to enable/disable the analytics records. Bun records bundle timings (so we can answer with data, "is Bun getting faster?") and feature usage (e.g., "are people actually using macros?"). The request body size is about 60 bytes, so it's not a lot of data. By default the telemetry is enabled. Equivalent of `DO_NOT_TRACK` env variable.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 telemetry = false
 ```
 
@@ -117,7 +121,7 @@ Configure console output behavior.
 
 Set the default depth for `console.log()` object inspection. Default `2`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [console]
 depth = 3
 ```
@@ -128,7 +132,7 @@ This controls how deeply nested objects are displayed in console output. Higher
 
 The test runner is configured under the `[test]` section of your bunfig.toml.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 # configuration goes here
 ```
@@ -137,7 +141,7 @@ The test runner is configured under the `[test]` section of your bunfig.toml.
 
 The root directory to run tests from. Default `.`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 root = "./__tests__"
 ```
@@ -146,7 +150,7 @@ root = "./__tests__"
 
 Same as the top-level `preload` field, but only applies to `bun test`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 preload = ["./setup.ts"]
 ```
@@ -155,7 +159,7 @@ preload = ["./setup.ts"]
 
 Same as the top-level `smol` field, but only applies to `bun test`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 smol = true
 ```
@@ -164,7 +168,7 @@ smol = true
 
 Enables coverage reporting. Default `false`. Use `--coverage` to override.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 coverage = false
 ```
@@ -173,7 +177,7 @@ coverage = false
 
 To specify a coverage threshold. By default, no threshold is set. If your test suite does not meet or exceed this threshold, `bun test` will exit with a non-zero exit code to indicate the failure.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 
 # to require 90% line-level and function-level coverage
@@ -182,7 +186,7 @@ coverageThreshold = 0.9
 
 Different thresholds can be specified for line-wise, function-wise, and statement-wise coverage.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }
 ```
@@ -191,7 +195,7 @@ coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }
 
 Whether to skip test files when computing coverage statistics. Default `false`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 coverageSkipTestFiles = false
 ```
@@ -200,7 +204,7 @@ coverageSkipTestFiles = false
 
 Exclude specific files or file patterns from coverage reports using glob patterns. Can be a single string pattern or an array of patterns.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 # Single pattern
 coveragePathIgnorePatterns = "**/*.spec.ts"
@@ -218,7 +222,7 @@ coveragePathIgnorePatterns = [
 
 By default, coverage reports will be printed to the console. For persistent code coverage reports in CI environments and for other tools use `lcov`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 coverageReporter  = ["text", "lcov"]  # default ["text"]
 ```
@@ -227,68 +231,16 @@ coverageReporter  = ["text", "lcov"]  # default ["text"]
 
 Set path where coverage reports will be saved. Please notice, that it works only for persistent `coverageReporter` like `lcov`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 coverageDir = "path/to/somewhere"  # default "coverage"
 ```
 
-### `test.concurrentTestGlob`
-
-Specify a glob pattern to automatically run matching test files with concurrent test execution enabled. Test files matching this pattern will behave as if the `--concurrent` flag was passed, running all tests within those files concurrently.
-
-```toml
-[test]
-concurrentTestGlob = "**/concurrent-*.test.ts"
-```
-
-This is useful for:
-
-- Gradually migrating test suites to concurrent execution
-- Running integration tests concurrently while keeping unit tests sequential
-- Separating fast concurrent tests from tests that require sequential execution
-
-The `--concurrent` CLI flag will override this setting when specified.
-
-### `test.onlyFailures`
-
-When enabled, only failed tests are displayed in the output. This helps reduce noise in large test suites by hiding passing tests. Default `false`.
-
-```toml
-[test]
-onlyFailures = true
-```
-
-This is equivalent to using the `--only-failures` flag when running `bun test`.
-
-### `test.reporter`
-
-Configure the test reporter settings.
-
-#### `test.reporter.dots`
-
-Enable the dots reporter, which displays a compact output showing a dot for each test. Default `false`.
-
-```toml
-[test.reporter]
-dots = true
-```
-
-#### `test.reporter.junit`
-
-Enable JUnit XML reporting and specify the output file path.
-
-```toml
-[test.reporter]
-junit = "test-results.xml"
-```
-
-This generates a JUnit XML report that can be consumed by CI systems and other tools.
-
 ### `test.randomize`
 
 Run tests in random order. Default `false`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 randomize = true
 ```
@@ -301,7 +253,7 @@ The `--randomize` CLI flag will override this setting when specified.
 
 Set the random seed for test randomization. This option requires `randomize` to be `true`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 randomize = true
 seed = 2444615283
@@ -315,7 +267,7 @@ The `--seed` CLI flag will override this setting when specified.
 
 Re-run each test file a specified number of times. Default `0` (run once).
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [test]
 rerunEach = 3
 ```
@@ -328,7 +280,7 @@ The `--rerun-each` CLI flag will override this setting when specified.
 
 Package management is a complex issue; to support a range of use cases, the behavior of `bun install` can be configured under the `[install]` section.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 # configuration here
 ```
@@ -337,7 +289,7 @@ Package management is a complex issue; to support a range of use cases, the beha
 
 Whether to install optional dependencies. Default `true`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 optional = true
 ```
@@ -346,7 +298,7 @@ optional = true
 
 Whether to install development dependencies. Default `true`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 dev = true
 ```
@@ -355,7 +307,7 @@ dev = true
 
 Whether to install peer dependencies. Default `true`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 peer = true
 ```
@@ -366,7 +318,7 @@ Whether `bun install` will run in "production mode". Default `false`.
 
 In production mode, `"devDependencies"` are not installed. You can use `--production` in the CLI to override this setting.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 production = false
 ```
@@ -377,7 +329,7 @@ Whether to set an exact version in `package.json`. Default `false`.
 
 By default Bun uses caret ranges; if the `latest` version of a package is `2.4.1`, the version range in your `package.json` will be `^2.4.1`. This indicates that any version from `2.4.1` up to (but not including) `3.0.0` is acceptable.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 exact = false
 ```
@@ -388,80 +340,34 @@ If false, generate a binary `bun.lockb` instead of a text-based `bun.lock` file
 
 Default `true` (since Bun v1.2).
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 saveTextLockfile = false
 ```
 
-<!--
-### `install.prefer`
-
-Whether the package manager should prefer offline or online dependency resolution. Default `"online"`.
-
-```toml
-[install]
-prefer = "online"
-```
-
-Valid values are:
-
-{% table %}
-
----
-
-- `"online"`
-- Prefer online resolution. This is the default. If a package is not found in the local cache, it will be downloaded from the registry.
-
----
-
-- `"offline"`
-- Prefer offline resolution. When possible, packages will be installed from the global cache. This minimizes the fraction of the time Bun will check for newer versions from the registry. If a package is not found in the global cache, it will be downloaded from the registry.
-
-{% /table %} -->
-
 ### `install.auto`
 
 To configure Bun's package auto-install behavior. Default `"auto"` — when no `node_modules` folder is found, Bun will automatically install dependencies on the fly during execution.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 auto = "auto"
 ```
 
 Valid values are:
 
-{% table %}
-
-- Value
-- Description
-
----
-
-- `"auto"`
-- Resolve modules from local `node_modules` if it exists. Otherwise, auto-install dependencies on the fly.
-
----
-
-- `"force"`
-- Always auto-install dependencies, even if `node_modules` exists.
-
----
-
-- `"disable"`
-- Never auto-install dependencies.
-
----
-
-- `"fallback"`
-- Check local `node_modules` first, then auto-install any packages that aren't found. You can enable this from the CLI with `bun -i`.
-
-{% /table %}
+| Value        | Description                                                                                                                         |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `"auto"`     | Resolve modules from local `node_modules` if it exists. Otherwise, auto-install dependencies on the fly.                            |
+| `"force"`    | Always auto-install dependencies, even if `node_modules` exists.                                                                    |
+| `"disable"`  | Never auto-install dependencies.                                                                                                    |
+| `"fallback"` | Check local `node_modules` first, then auto-install any packages that aren't found. You can enable this from the CLI with `bun -i`. |
 
 ### `install.frozenLockfile`
 
 When true, `bun install` will not update `bun.lock`. Default `false`. If `package.json` and the existing `bun.lock` are not in agreement, this will error.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 frozenLockfile = false
 ```
@@ -470,7 +376,7 @@ frozenLockfile = false
 
 Whether `bun install` will actually install dependencies. Default `false`. When true, it's equivalent to setting `--dry-run` on all `bun install` commands.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 dryRun = false
 ```
@@ -481,7 +387,7 @@ To configure the directory where Bun puts globally installed packages.
 
 Environment variable: `BUN_INSTALL_GLOBAL_DIR`
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 # where `bun install --global` installs packages
 globalDir = "~/.bun/install/global"
@@ -493,7 +399,7 @@ To configure the directory where Bun installs globally installed binaries and CL
 
 Environment variable: `BUN_INSTALL_BIN`
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 # where globally-installed package bins are linked
 globalBinDir = "~/.bun/bin"
 ```
@@ -502,7 +408,7 @@ globalBinDir = "~/.bun/bin"
 
 The default registry is `https://registry.npmjs.org/`. This can be globally configured in `bunfig.toml`:
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 # set default registry as a string
 registry = "https://registry.npmjs.org"
@@ -518,7 +424,7 @@ To configure how workspace packages are linked, use the `install.linkWorkspacePa
 
 Whether to link workspace packages from the monorepo root to their respective `node_modules` directories. Default `true`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 linkWorkspacePackages = true
 ```
@@ -527,7 +433,7 @@ linkWorkspacePackages = true
 
 To configure a registry for a particular scope (e.g. `@myorg/<package>`) use `install.scopes`. You can reference environment variables with `$variable` notation.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install.scopes]
 # registry as string
 myorg = "https://username:password@registry.myorg.com/"
@@ -544,7 +450,7 @@ myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }
 
 To configure a CA certificate, use `install.ca` or `install.cafile` to specify a path to a CA certificate file.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 # The CA certificate as a string
 ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
@@ -557,7 +463,7 @@ cafile = "path/to/cafile"
 
 To configure the cache behavior:
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install.cache]
 
 # the directory to use for the cache
@@ -577,92 +483,37 @@ To configure lockfile behavior, use the `install.lockfile` section.
 
 Whether to generate a lockfile on `bun install`. Default `true`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install.lockfile]
 save = true
 ```
 
 Whether to generate a non-Bun lockfile alongside `bun.lock`. (A `bun.lock` will always be created.) Currently `"yarn"` is the only supported value.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install.lockfile]
 print = "yarn"
 ```
 
-### `install.security.scanner`
-
-Configure a security scanner to scan packages for vulnerabilities before installation.
-
-First, install a security scanner from npm:
-
-```bash
-$ bun add -d @acme/bun-security-scanner
-```
-
-Then configure it in your `bunfig.toml`:
-
-```toml
-[install.security]
-scanner = "@acme/bun-security-scanner"
-```
-
-When a security scanner is configured:
-
-- Auto-install is automatically disabled for security
-- Packages are scanned before installation
-- Installation is cancelled if fatal issues are found
-- Security warnings are displayed during installation
-
-Learn more about [using and writing security scanners](/docs/install/security-scanner-api).
-
 ### `install.linker`
 
-Configure the default linker strategy. Default `"hoisted"`.
+Configure the default linker strategy. Default `"hoisted"` for single-project projects, `"isolated"` for monorepo projects.
 
-For complete documentation refer to [Package manager > Isolated installs](https://bun.com/docs/install/isolated).
+For complete documentation refer to [Package manager > Isolated installs](/pm/isolated-installs).
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [install]
 linker = "hoisted"
 ```
 
 Valid values are:
 
-{% table %}
-
-- Value
-- Description
-
----
-
-- `"hoisted"`
-- Link dependencies in a shared `node_modules` directory.
-
----
-
-- `"isolated"`
-- Link dependencies inside each package installation.
-
-{% /table %}
-
-### `install.minimumReleaseAge`
-
-Configure a minimum age (in seconds) for npm package versions. Package versions published more recently than this threshold will be filtered out during installation. Default is `null` (disabled).
+| Value        | Description                                             |
+| ------------ | ------------------------------------------------------- |
+| `"hoisted"`  | Link dependencies in a shared `node_modules` directory. |
+| `"isolated"` | Link dependencies inside each package installation.     |
 
-```toml
-[install]
-# Only install package versions published at least 3 days ago
-minimumReleaseAge = 259200
-# These packages will bypass the 3-day minimum age requirement
-minimumReleaseAgeExcludes = ["@types/bun", "typescript"]
-```
-
-For more details see [Minimum release age](https://bun.com/docs/cli/install#minimum-release-age) in the install documentation.
-
-<!-- ## Debugging -->
-
-<!--
-```toml
+```toml title="bunfig.toml" icon="settings"
 [debug]
 # When navigating to a blob: or src: link, open the file in your editor
 # If not, it tries $EDITOR or $VISUAL
@@ -680,13 +531,26 @@ editor = "code"
 # - "vim","vi"
 # - "emacs"
 ```
--->
+
+### `install.minimumReleaseAge`
+
+Configure a minimum age (in seconds) for npm package versions. Package versions published more recently than this threshold will be filtered out during installation. Default is `null` (disabled).
+
+```toml title="bunfig.toml" icon="settings"
+[install]
+# Only install package versions published at least 3 days ago
+minimumReleaseAge = 259200
+# These packages will bypass the 3-day minimum age requirement
+minimumReleaseAgeExcludes = ["@types/bun", "typescript"]
+```
+
+For more details see [Minimum release age](/pm/cli/install#minimum-release-age) in the install documentation.
 
 ## `bun run`
 
 The `bun run` command can be configured under the `[run]` section. These apply to the `bun run` command and the `bun` command when running a file or executable or script.
 
-Currently, `bunfig.toml` is only automatically loaded for `bun run` in a local project (it doesn't check for a global `.bunfig.toml`).
+Currently, `bunfig.toml` isn't always automatically loaded for `bun run` in a local project (it does check for a global `bunfig.toml`), so you might still need to pass `-c` or `-c=bunfig.toml` to use these settings.
 
 ### `run.shell` - use the system shell or Bun's shell
 
@@ -694,7 +558,7 @@ The shell to use when running package.json scripts via `bun run` or `bun`. On Wi
 
 To always use the system shell instead of Bun's shell (default behavior unless Windows):
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [run]
 # default outside of Windows
 shell = "system"
@@ -702,7 +566,7 @@ shell = "system"
 
 To always use Bun's shell instead of the system shell:
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [run]
 # default on Windows
 shell = "bun"
@@ -716,7 +580,7 @@ This means that if you have a script that runs `node`, it will actually run `bun
 
 By default, this is enabled if `node` is not already in your `$PATH`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [run]
 # equivalent to `bun --bun` for all `bun run` commands
 bun = true
@@ -725,8 +589,8 @@ bun = true
 You can test this by running:
 
 ```sh
-$ bun --bun which node # /path/to/bun
-$ bun which node # /path/to/node
+bun --bun which node # /path/to/bun
+bun which node # /path/to/node
 ```
 
 This option is equivalent to prefixing all `bun run` commands with `--bun`:
@@ -743,23 +607,29 @@ If set to `false`, this will disable the `node` symlink.
 
 When `true`, suppresses the output of the command being run by `bun run` or `bun`.
 
-```toml
+```toml title="bunfig.toml" icon="settings"
 [run]
 silent = true
 ```
 
 Without this option, the command being run will be printed to the console:
 
-```sh
-$ bun run dev
-> $ echo "Running \"dev\"..."
+```sh terminal icon="terminal"
+bun run dev
+echo "Running \"dev\"..."
+```
+
+```txt
 Running "dev"...
 ```
 
 With this option, the command being run will not be printed to the console:
 
 ```sh
-$ bun run dev
+bun run dev
+```
+
+```txt
 Running "dev"...
 ```