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

> Configure bunfig.toml for project-specific Bun settings. Define runtime, test, and package manager defaults easily. Learn how to manage Bun configuration for your projects.

- Repository: [Bun/bun](https://github.com/oven-sh/bun)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Create a [`bunfig.toml`](https://github.com/oven-sh/bun/blob/main/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`](https://github.com/oven-sh/bun/blob/main/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`](https://github.com/oven-sh/bun/blob/main/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`](https://github.com/oven-sh/bun/blob/main/src/bunfig.zig) and documented in [`docs/runtime/bunfig.mdx`](https://github.com/oven-sh/bun/blob/main/docs/runtime/bunfig.mdx).

## Configuration File Locations and Precedence

Bun searches for [`bunfig.toml`](https://github.com/oven-sh/bun/blob/main/bunfig.toml) in two locations and merges them hierarchically. Local values always override global ones.

- **Project-level**: [`./bunfig.toml`](https://github.com/oven-sh/bun/blob/main/./bunfig.toml) (next to [`package.json`](https://github.com/oven-sh/bun/blob/main/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`](https://github.com/oven-sh/bun/blob/main/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.

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

```

### JSX Transformation

Control JSX compilation without modifying [`tsconfig.json`](https://github.com/oven-sh/bun/blob/main/tsconfig.json). These settings override TypeScript `compilerOptions` when present.

```toml
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.

```toml
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.

```toml
[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.

```toml
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.

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

```

### Code Coverage Settings

Enable coverage collection with configurable thresholds and output formats.

```toml
[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.

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

```

### Reporter Output

Customize the test output format for CI integration.

```toml
[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.

```toml
[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.

```toml
[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.

```toml
[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.

```toml
[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.

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

```

## Debug and Editor Integration ([debug])

Configure editor integration for debug workflows.

```toml
[debug]
editor = "code"

```

## Complete Project Configuration Example

Save this comprehensive [`bunfig.toml`](https://github.com/oven-sh/bun/blob/main/bunfig.toml) at your project root to demonstrate production-ready settings:

```toml

# 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`](https://github.com/oven-sh/bun/blob/main/bunfig.toml) next to [`package.json`](https://github.com/oven-sh/bun/blob/main/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`](https://github.com/oven-sh/bun/blob/main/src/bunfig.zig) while documentation resides in [`docs/runtime/bunfig.mdx`](https://github.com/oven-sh/bun/blob/main/docs/runtime/bunfig.mdx).

## Frequently Asked Questions

### Does Bun require a bunfig.toml file?

No. Bun operates perfectly without a [`bunfig.toml`](https://github.com/oven-sh/bun/blob/main/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`](https://github.com/oven-sh/bun/blob/main/bunfig.toml) takes precedence over global configuration. If both `$HOME/.bunfig.toml` (or `$XDG_CONFIG_HOME/.bunfig.toml`) and [`./bunfig.toml`](https://github.com/oven-sh/bun/blob/main/./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.