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. ```toml # 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. ```toml jsx = "react" jsxFactory = "h" jsxFragment = "Fragment" 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) ### `smol` Enable `smol` mode. This reduces memory usage at the cost of performance. ```toml # Reduce memory usage at the cost of performance smol = true ``` ### `logLevel` Set the log level. This can be one of `"debug"`, `"warn"`, or `"error"`. ```toml 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. ```toml [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 ```toml [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. ```toml [test] # configuration goes here ``` ### `test.root` The root directory to run tests from. Default `.`. ```toml [test] root = "./__tests__" ``` ### `test.preload` Same as the top-level `preload` field, but only applies to `bun test`. ```toml [test] preload = ["./setup.ts"] ``` ### `test.smol` Same as the top-level `smol` field, but only applies to `bun test`. ```toml [test] smol = true ``` ### `test.coverage` Enables coverage reporting. Default `false`. Use `--coverage` to override. ```toml [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. ```toml [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. ```toml [test] coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 } ``` ### `test.coverageSkipTestFiles` Whether to skip test files when computing coverage statistics. Default `false`. ```toml [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. ```toml [install] # configuration here ``` ### `install.optional` Whether to install optional dependencies. Default `true`. ```toml [install] optional = true ``` ### `install.dev` Whether to install development dependencies. Default `true`. ```toml [install] dev = true ``` ### `install.peer` Whether to install peer dependencies. Default `false`. ```toml [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. ```toml [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. ```toml [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. ```toml [install] auto = "auto" ``` Valid values are: {% table %} --- - `"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. ```toml [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. ```toml [install] dryRun = false ``` ### `install.globalDir` To configure the directory where Bun puts globally installed packages. ```toml [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. ```toml # 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`: ```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/`) use `install.scopes`. You can reference environment variables with `$variable` notation. ```toml [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: ```toml [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`. ```toml [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. ```toml [install.lockfile] print = "yarn" ```