How to Configure bunfig.toml for Project-Specific Bun Settings: Complete Reference Guide

Create a bunfig.toml file in your project root to define runtime, test, and package manager defaults that Bun automatically loads and merges with global settings.

The bunfig.toml file is Bun's optional configuration mechanism that allows you to customize the runtime, test runner, and package manager on a per-project basis. According to the oven-sh/bun source code, when placed next to package.json, Bun automatically loads this file and shallow-merges it with global configuration, letting you configure project-specific Bun settings without repeating CLI flags. The configuration is parsed by src/bunfig.zig and documented in docs/runtime/bunfig.mdx.

Configuration File Locations and Precedence

Bun searches for bunfig.toml in two locations and merges them hierarchically. Local values always override global ones.

• Project-level: ./bunfig.toml (next to package.json)
• Global: $HOME/.bunfig.toml or $XDG_CONFIG_HOME/.bunfig.toml

When both files exist, Bun performs a shallow merge where project-specific settings take precedence. This enables consistent team defaults while allowing personal overrides for global tools.

Runtime-Level Settings

Configure the Bun runtime behavior for bun run and module resolution using top-level keys in bunfig.toml.

Preload Scripts and Polyfills

The preload array specifies scripts or plugins that Bun executes before running any application code. This is useful for registering global plugins, polyfills, or custom instrumentation.

preload = ["./preload.ts", "./instrumentation.ts"]

JSX Transformation

Control JSX compilation without modifying tsconfig.json. These settings override TypeScript compilerOptions when present.

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

Memory and Performance Tuning

Enable smol mode to reduce memory usage at the cost of performance—ideal for resource-constrained environments like CI containers.

smol = true
logLevel = "warn"

Compile-Time Definitions and Loaders

Replace global identifiers at compile-time using the [define] table, or map custom file extensions to built-in loaders.

[define]
"process.env.API_URL" = "'https://api.example.com'"

[loader]
".bagel" = "tsx"
".wgsl" = "text"

Environment and Telemetry Control

Disable automatic .env loading or anonymous crash reporting telemetry.

env = false
telemetry = false

Test Runner Configuration ([test])

The [test] section customizes bun test behavior, including coverage thresholds, test discovery, and retry logic.

Test Discovery and Execution

Set the root directory for test file scanning and configure preloads specific to the test environment.

[test]
root = "./__tests__"
preload = ["./tests/setup.ts"]
smol = true

Code Coverage Settings

Enable coverage collection with configurable thresholds and output formats.

[test]
coverage = true
coverageThreshold = { line = 0.8, function = 0.85, statement = 0.9 }
coverageSkipTestFiles = true
coverageReporter = ["text", "lcov"]
coverageDir = "coverage"

Flaky Test Detection and Retries

Configure automatic retries and concurrent execution patterns to detect flaky tests.

[test]
retry = 2
rerunEach = 3
randomize = true
seed = 2444615283
concurrentTestGlob = "**/concurrent-*.test.ts"

Reporter Output

Customize the test output format for CI integration.

[test.reporter]
dots = true
junit = "test-results.xml"
onlyFailures = true

Package Manager Configuration ([install])

The [install] section controls bun install behavior, registry settings, and lockfile management.

Dependency Installation Modes

Control which dependency types to install and how to handle lockfiles.

[install]
production = true
optional = true
dev = true
frozenLockfile = true
auto = "disable"

Registry and Authentication

Configure npm registries with token-based authentication or scope-specific overrides. The scopes table supports environment variable interpolation.

[install]
registry = { url = "https://registry.npmjs.org", token = "$NPM_TOKEN" }
exact = false
saveTextLockfile = true

[install.scopes]
myorg = "https://user:pass@registry.myorg.com/"

Security and Linking

Set custom CA certificates, minimum package age requirements, and linking strategies.

[install]
linker = "isolated"
minimumReleaseAge = 259200
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]
cafile = "./custom-ca.pem"

[install.security]
scanner = "@acme/bun-security-scanner"

Cache Configuration

Customize the package cache directory and behavior.

[install.cache]
dir = "~/.bun/install/cache"
disable = false

Run Command Configuration ([run])

The [run] section configures how bun run executes package.json scripts.

Shell and Execution Behavior

Choose between system shell and Bun's built-in shell, or enable automatic node aliasing.

[run]
shell = "system"
bun = true
silent = true

Debug and Editor Integration ([debug])

Configure editor integration for debug workflows.

[debug]
editor = "code"

Complete Project Configuration Example

Save this comprehensive bunfig.toml at your project root to demonstrate production-ready settings:

# Project-specific Bun configuration

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

# JSX handling for non-TypeScript projects

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

# CI-optimized settings

smol = true
logLevel = "warn"

# Global constant replacements

[define]
"process.env.NODE_ENV" = "'production'"

# Custom file loaders

[loader]
".bagel" = "tsx"

# Test runner configuration

[test]
root = "./tests"
preload = ["./tests/setup.ts"]
coverage = true
coverageThreshold = { line = 0.8, function = 0.85 }
coverageReporter = ["text", "lcov"]
randomize = true
seed = 123456
rerunEach = 2
onlyFailures = true

[test.reporter]
dots = true

# Package manager CI settings

[install]
production = true
auto = "disable"
frozenLockfile = true
registry = { url = "https://registry.npmjs.org", token = "$NPM_TOKEN" }
minimumReleaseAge = 259200
minimumReleaseAgeExcludes = ["typescript"]

[install.cache]
dir = "~/.bun/install/cache"

# Run command defaults

[run]
bun = true
silent = true

Bun automatically merges this configuration with any global settings and applies them to bun run, bun test, and bun install commands.

Summary

• Location matters: Place bunfig.toml next to package.json for project-specific settings; Bun merges it with $HOME/.bunfig.toml automatically.
• Top-level keys control runtime behavior including preload, jsx transformation, smol mode, and compile-time define replacements.
• The [test] section configures coverage thresholds, retry logic, randomization seeds, and reporter formats for the test runner.
• The [install] section manages registry authentication, lockfile behavior, security scanning, and package linking strategies.
• Source references: The parser lives in src/bunfig.zig while documentation resides in docs/runtime/bunfig.mdx.

Frequently Asked Questions

Does Bun require a bunfig.toml file?

No. Bun operates perfectly without a bunfig.toml file, using sensible defaults for all settings. The configuration file is entirely optional and only necessary when you need to customize runtime, test, or package manager behavior beyond CLI flags.

How does Bun merge global and local bunfig.toml files?

Bun performs a shallow merge where the local project bunfig.toml takes precedence over global configuration. If both $HOME/.bunfig.toml (or $XDG_CONFIG_HOME/.bunfig.toml) and ./bunfig.toml exist, Bun loads the global file first, then overlays local values on top.

Can I use environment variables in bunfig.toml values?

Yes, but only in specific contexts. The [install.scopes] table and registry token configurations support environment variable interpolation using $VAR or ${VAR} syntax. For example: token = "$NPM_TOKEN" or myorg = "https://user:${PASSWORD}@registry.com/".

What happens if I set both smol mode and high log levels?

Bun applies both settings independently. Setting smol = true reduces memory usage across the runtime, while logLevel = "debug" increases verbosity. These operate on different subsystems—smol mode affects the garbage collector and memory allocator, while log level controls console output filtering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}