bun.sh/docs/runtime/bunfig.md

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.

Global vs. local

In general, it's recommended to add a bunfig.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

If both a global and local 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 the bunfig.toml file.

preload

An array of scripts to execute before running a file or script. This is useful for registering plugins.

# scripts to run before `bun run`ning a file or script
# useful for registering plugins
preload = ["./preload.ts"]

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.

jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"

Refer to the tsconfig docs for more information on these fields.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

Enable smol mode. This reduces memory usage at the cost of performance.

# Reduce memory usage at the cost of performance
smol = true

logLevel

Set the log level. This can be one of "debug", "warn", or "error".

logLevel = "debug" # "debug" | "warn" | "error"

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.

[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.
# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing.
"process.env.bagel" = "'lox'"

loader

Configure how Bun maps file extensions to loaders. This is useful for loading files that aren't natively supported by Bun. If

[loader]
# when a .bagel file is imported, treat it like a tsx file
".bagel" = "tsx"

Bun supports the following loaders:

• jsx
• js
• ts
• tsx
• css
• file
• json
• toml
• wasm
• napi
• base64
• dataurl
• text

Test runner

The test runner is configured under the [test] section of your bunfig.toml.

[test]
# configuration goes here

test.root

The root directory to run tests from. Default ..

[test]
root = "./__tests__"

test.preload

Same as the top-level preload field, but only applies to bun test.

[test]
preload = ["./setup.ts"]

test.smol

Same as the top-level smol field, but only applies to bun test.

[test]
smol = true

test.coverage

Enables coverage reporting. Default false. Use --coverage to override.

[test]
coverage = false

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.

[test]

# to require 90% line-level and function-level coverage
coverageThreshold = 0.9

Different thresholds can be specified for line-wise, function-wise, and statement-wise coverage.

[test]
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }

test.coverageSkipTestFiles

Whether to skip test files when computing coverage statistics. Default false.

[test]
coverageSkipTestFiles = false

Package manager

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.

[install]
# configuration here

install.optional

Whether to install optional dependencies. Default true.

[install]
optional = true

install.dev

Whether to install development dependencies. Default true.

[install]
dev = true

install.peer

Whether to install peer dependencies. Default false.

[install]
peer = false

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.

[install]
production = false

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.

[install]
exact = false

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.

[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, the auto-install any packages that aren't found. You can enable this from the CLI with bun -i.

{% /table %}

install.frozenLockfile

When true, bun install will not update bun.lockb. Default false. If package.json and the existing bun.lockb are not in agreement, this will error.

[install]
frozenLockfile = false

install.dryRun

Whether to install optional dependencies. Default false. When true, it's equivalent to setting --dry-run on all bun install commands.

[install]
dryRun = false

install.globalDir

To configure the directory where Bun puts globally installed packages.

[install]
# where `bun install --global` installs packages
globalDir = "~/.bun/install/global"

install.globalBinDir

To configure the directory where Bun installs globally installed binaries and CLIs.

# where globally-installed package bins are linked
globalBinDir = "~/.bun/bin"

install.registry

The default registry is https://registry.npmjs.org/. This can be globally configured in bunfig.toml:

[install]
# set default registry as a string
registry = "https://registry.npmjs.org"
# set a token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# set a username/password
registry = "https://username:password@registry.npmjs.org"

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.

[install.scopes]
# registry as string
myorg = "https://username:password@registry.myorg.com/"

# registry with username/password
# you can reference environment variables
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# registry with token
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

install.cache

To configure the cache behavior:

[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

install.lockfile

To configure lockfile behavior, use the install.lockfile section.

Whether to generate a lockfile on bun install. Default true.

[install.lockfile]
save = true

Whether to generate a non-Bun lockfile alongside bun.lockb. (A bun.lockb will always be created.) Currently "yarn" is the only supported value.

[install.lockfile]
print = "yarn"