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.
Global vs. local
In general, it’s recommended to add abunfig.toml file to your project root, alongside your package.json.
To configure Bun globally, you can also create a .bunfig.toml file at one of the following paths:
$HOME/.bunfig.toml$XDG_CONFIG_HOME/.bunfig.toml
bunfig are detected, the results are shallow-merged, with local overriding global. CLI flags will override bunfig setting where applicable.
Runtime
Bun’s runtime behavior is configured using top-level fields in thebunfig.toml file.
preload
An array of scripts/plugins to execute before running a file or script.
bunfig.toml
jsx
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.
bunfig.toml
smol
Enable smol mode. This reduces memory usage at the cost of performance.
bunfig.toml
logLevel
Set the log level. This can be one of "debug", "warn", or "error".
bunfig.toml
define
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.
bunfig.toml
loader
Configure how Bun maps file extensions to loaders. This is useful for loading files that aren’t natively supported by Bun.
bunfig.toml
jsxjststsxcssfilejsontomlwasmnapibase64dataurltext
telemetry
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.
bunfig.toml
console
Configure console output behavior.
console.depth
Set the default depth for console.log() object inspection. Default 2.
bunfig.toml
--console-depth CLI flag.
Test runner
The test runner is configured under the[test] section of your bunfig.toml.
bunfig.toml
test.root
The root directory to run tests from. Default ..
bunfig.toml
test.preload
Same as the top-level preload field, but only applies to bun test.
bunfig.toml
test.smol
Same as the top-level smol field, but only applies to bun test.
bunfig.toml
test.coverage
Enables coverage reporting. Default false. Use --coverage to override.
bunfig.toml
test.coverageThreshold
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.
bunfig.toml
bunfig.toml
test.coverageSkipTestFiles
Whether to skip test files when computing coverage statistics. Default false.
bunfig.toml
test.coveragePathIgnorePatterns
Exclude specific files or file patterns from coverage reports using glob patterns. Can be a single string pattern or an array of patterns.
bunfig.toml
test.coverageReporter
By default, coverage reports will be printed to the console. For persistent code coverage reports in CI environments and for other tools use lcov.
bunfig.toml
test.coverageDir
Set path where coverage reports will be saved. Please notice, that it works only for persistent coverageReporter like lcov.
bunfig.toml
test.randomize
Run tests in random order. Default false.
bunfig.toml
seed, the random order becomes reproducible.
The --randomize CLI flag will override this setting when specified.
test.seed
Set the random seed for test randomization. This option requires randomize to be true.
bunfig.toml
--seed CLI flag will override this setting when specified.
test.rerunEach
Re-run each test file a specified number of times. Default 0 (run once).
bunfig.toml
--rerun-each CLI flag will override this setting when specified.
Package manager
Package management is a complex issue; to support a range of use cases, the behavior ofbun install can be configured under the [install] section.
bunfig.toml
install.optional
Whether to install optional dependencies. Default true.
bunfig.toml
install.dev
Whether to install development dependencies. Default true.
bunfig.toml
install.peer
Whether to install peer dependencies. Default true.
bunfig.toml
install.production
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.
bunfig.toml
install.exact
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.
bunfig.toml
install.saveTextLockfile
If false, generate a binary bun.lockb instead of a text-based bun.lock file when running bun install and no lockfile is present.
Default true (since Bun v1.2).
bunfig.toml
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.
bunfig.toml
| 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.
bunfig.toml
install.dryRun
Whether bun install will actually install dependencies. Default false. When true, it’s equivalent to setting --dry-run on all bun install commands.
bunfig.toml
install.globalDir
To configure the directory where Bun puts globally installed packages.
Environment variable: BUN_INSTALL_GLOBAL_DIR
bunfig.toml
install.globalBinDir
To configure the directory where Bun installs globally installed binaries and CLIs.
Environment variable: BUN_INSTALL_BIN
bunfig.toml
install.registry
The default registry is https://registry.npmjs.org/. This can be globally configured in bunfig.toml:
bunfig.toml
install.linkWorkspacePackages
To configure how workspace packages are linked, use the install.linkWorkspacePackages option.
Whether to link workspace packages from the monorepo root to their respective node_modules directories. Default true.
bunfig.toml
install.scopes
To configure a registry for a particular scope (e.g. @myorg/<package>) use install.scopes. You can reference environment variables with $variable notation.
bunfig.toml
install.ca and install.cafile
To configure a CA certificate, use install.ca or install.cafile to specify a path to a CA certificate file.
bunfig.toml
install.cache
To configure the cache behavior:
bunfig.toml
install.lockfile
To configure lockfile behavior, use the install.lockfile section.
Whether to generate a lockfile on bun install. Default true.
bunfig.toml
bun.lock. (A bun.lock will always be created.) Currently "yarn" is the only supported value.
bunfig.toml
install.linker
Configure the default linker strategy. Default "hoisted" for single-project projects, "isolated" for monorepo projects.
For complete documentation refer to Package manager > Isolated installs.
bunfig.toml
| Value | Description |
|---|---|
"hoisted" | Link dependencies in a shared node_modules directory. |
"isolated" | Link dependencies inside each package installation. |
bunfig.toml
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).
bunfig.toml
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 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
The shell to use when running package.json scripts via bun run or bun. On Windows, this defaults to "bun" and on other platforms it defaults to "system".
To always use the system shell instead of Bun’s shell (default behavior unless Windows):
bunfig.toml
bunfig.toml
run.bun - auto alias node to bun
When true, this prepends $PATH with a node symlink that points to the bun binary for all scripts or executables invoked by bun run or bun.
This means that if you have a script that runs node, it will actually run bun instead, without needing to change your script. This works recursively, so if your script runs another script that runs node, it will also run bun instead. This applies to shebangs as well, so if you have a script with a shebang that points to node, it will actually run bun instead.
By default, this is enabled if node is not already in your $PATH.
bunfig.toml
bun run commands with --bun:
false, this will disable the node symlink.
run.silent - suppress reporting the command being run
When true, suppresses the output of the command being run by bun run or bun.
bunfig.toml
terminal
--silent to all bun run commands: