> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# bunfig.toml

> Configure Bun's runtime behavior with bunfig.toml

`bunfig.toml` is Bun's configuration file for customizing runtime behavior, package management, and build settings.

## Location

Bun searches for `bunfig.toml` in these locations (in order):

1. Current directory: `./bunfig.toml`
2. Parent directories (walks up)
3. User home: `~/.bunfig.toml` or `$BUN_CONFIG_PATH`
4. System-wide: `/etc/bunfig.toml` (Linux)

<Note>
  Project-specific `bunfig.toml` overrides user/system configuration.
</Note>

## Basic Structure

```toml bunfig.toml theme={null}
# Runtime configuration
preload = ["./setup.ts"]
logLevel = "info"

# Environment variables
[env]
file = [".env", ".env.local"]

# Package manager
[install]
registry = "https://registry.npmjs.org/"

# Development server
[dev]
port = 3000
```

## Runtime Configuration

### Log Level

Control console output verbosity:

```toml Log level theme={null}
logLevel = "debug" # debug, info, warn, error
```

Implementation: `src/bunfig.zig:109-123` - Log level parsing

### Preload Scripts

Execute scripts before main entry point:

```toml Preload theme={null}
preload = [
  "./setup.ts",
  "./polyfills.ts",
  "./instrumentation.ts"
]
```

**Use cases:**

* Environment setup
* Polyfills
* Global initialization
* Monkey-patching

Implementation: `src/bunfig.zig:125-149` - Preload parsing

## Environment Variables

Configure `.env` file loading:

```toml Environment configuration theme={null}
[env]
# Disable default .env loading
file = false

# Or specify custom files
file = [".env", ".env.custom"]
```

```toml Environment object theme={null}
[env]
file = { file = false }  # Disable
```

Implementation: `src/bunfig.zig:151-186` - Env config parsing

## Package Manager

Configure `bun install` behavior:

### Registry

Custom npm registry:

```toml Registry theme={null}
[install]
registry = "https://registry.npmjs.org/"

# With authentication
registry = "https://username:password@registry.example.com/"
```

```toml Registry object theme={null}
[install.registry]
url = "https://registry.example.com/"
username = "user"
password = "pass"
token = "npm_xxx"
```

Implementation: `src/bunfig.zig:45-107` - Registry parsing

### Scoped Registries

Different registries per scope:

```toml Scoped registries theme={null}
[install.scopes]
"@mycompany" = "https://npm.mycompany.com/"
"@other" = { url = "https://npm.other.com/", token = "xxx" }
```

### Cache

Configure package cache:

```toml Cache configuration theme={null}
[install]
cache = "~/.bun/install/cache" # Custom cache directory
cache = false # Disable cache
```

### Lockfile

Lockfile behavior:

```toml Lockfile theme={null}
[install]
lockfile = true  # Generate/update lockfile (default)
lockfile = false # Disable lockfile
```

### Production

Skip devDependencies:

```toml Production install theme={null}
[install]
production = true # Skip devDependencies
```

### Optional Dependencies

```toml Optional deps theme={null}
[install]
optional = true  # Install optionalDependencies (default)
optional = false # Skip optionalDependencies
```

### Exact Versions

```toml Exact versions theme={null}
[install]
exact = true # Install exact versions from lockfile
```

### Frozen Lockfile

```toml Frozen lockfile theme={null}
[install]
frozenLockfile = true # Error if lockfile would change
```

### Dry Run

```toml Dry run theme={null}
[install]
dryRun = true # Simulate install without writing files
```

## Development Server

Configure `bun --hot`:

```toml Dev server theme={null}
[dev]
port = 3000
host = "localhost"
```

## Test Runner

Configure `bun test`:

```toml Test configuration theme={null}
[test]
# Test file pattern
preload = ["./test-setup.ts"]
```

## Build Configuration

Configure `bun build`:

```toml Build config theme={null}
[build]
# Loader configuration
[build.loader]
".txt" = "text"
".data" = "json"
".png" = "file"
```

## Loader Configuration

Map file extensions to loaders:

```toml Loaders theme={null}
[loader]
".js" = "jsx"       # Treat .js as JSX
".data" = "json"    # Parse .data as JSON
".txt" = "text"     # Load .txt as text
".svg" = "text"     # SVG as text
".graphql" = "text" # GraphQL as text
```

See [Loaders documentation](/runtime/loaders) for available loaders.

## Macro Configuration

Configure build-time macros:

```toml Macros theme={null}
[macros]
# Import replacements
"react" = "preact/compat"
```

## Define

Replace identifiers at build time:

```toml Define theme={null}
[define]
PROCESS_ENV_NODE_ENV = '"production"'
VERSION = '"1.0.0"'
API_URL = '"https://api.example.com"'
```

Usage in code:

```javascript Using defines theme={null}
console.log(VERSION); // "1.0.0"
console.log(API_URL); // "https://api.example.com"

if (PROCESS_ENV_NODE_ENV === "production") {
  // Production-only code
}
```

## External Dependencies

Mark packages as external (not bundled):

```toml External theme={null}
external = ["fsevents", "lightningcss"]
```

## Compilation

Enable/disable features:

```toml Compilation theme={null}
[compile]
# Native compilation settings
```

## Example Configurations

### Minimal Configuration

```toml Minimal bunfig.toml theme={null}
logLevel = "info"
```

### Development Setup

```toml Development bunfig.toml theme={null}
logLevel = "debug"
preload = ["./dev-setup.ts"]

[env]
file = [".env.development", ".env.local"]

[install]
cache = true
lockfile = true

[dev]
port = 3000
```

### Production Setup

```toml Production bunfig.toml theme={null}
logLevel = "error"

[env]
file = ".env.production"

[install]
production = true
frozenLockfile = true
cache = "~/.bun/cache"

[define]
PROCESS_ENV_NODE_ENV = '"production"'
```

### Monorepo Configuration

```toml Monorepo bunfig.toml theme={null}
logLevel = "info"

[install]
workspace = true
hoistPattern = ["*"]

[install.scopes]
"@myorg" = "https://npm.myorg.com/"

[loader]
".tsx" = "tsx"
".graphql" = "text"
```

### Custom Registry

```toml Custom registry theme={null}
[install.registry]
url = "https://npm.internal.company.com/"
token = "${NPM_TOKEN}"

[install.scopes]
"@company" = "https://npm.internal.company.com/"
"@public" = "https://registry.npmjs.org/"
```

## TOML Syntax

Bun uses standard TOML format:

```toml TOML syntax theme={null}
# Comments
# Single line comment

# Strings
string = "double quotes"
singleQuote = 'single quotes'
multiline = """
Line 1
Line 2
"""

# Numbers
integer = 42
float = 3.14

# Booleans
bool = true

# Arrays
array = [1, 2, 3]
mixed = ["a", 1, true]

# Tables (objects)
[section]
key = "value"

# Nested tables
[section.subsection]
key = "value"

# Inline tables
inline = { key = "value", another = 42 }

# Array of tables
[[items]]
name = "First"

[[items]]
name = "Second"
```

## Environment Variable Expansion

Reference environment variables:

```toml Environment variables theme={null}
[install.registry]
url = "https://npm.company.com/"
token = "${NPM_TOKEN}" # Expands process.env.NPM_TOKEN

[define]
API_URL = '"${API_URL}"' # Expands process.env.API_URL
```

## Configuration Validation

Bun validates `bunfig.toml` on startup:

```bash Validate config theme={null}
bun run app.ts
# Error: Invalid Bunfig: Unknown key "invalidKey"
```

## Debugging Configuration

### Print Loaded Config

```bash Debug config theme={null}
BUN_DEBUG_QUIET_LOGS=0 bun run app.ts 2>&1 | grep -i bunfig
```

### Check Config Location

```javascript Check config theme={null}
import { bunfigPath } from "bun";
console.log(bunfigPath); // Path to loaded bunfig.toml
```

## Implementation

Configuration parsing implementation:

* **Parser**: `src/bunfig.zig` - TOML parsing and validation
* **Options**: `src/options.zig` - Configuration options
* **INI parser**: `src/ini.zig` - TOML/INI parsing utilities

```zig Bunfig structure (src/bunfig.zig:7-18) theme={null}
pub const Bunfig = struct {
    pub const OfflineMode = enum {
        online,
        latest,
        offline,
    };
    pub const Prefer = bun.ComptimeStringMap(OfflineMode, .{
        &.{ "offline", OfflineMode.offline },
        &.{ "latest", OfflineMode.latest },
        &.{ "online", OfflineMode.online },
    });
};
```

## Common Patterns

### Multi-Environment Setup

Use environment-specific configs:

```bash Project structure theme={null}
.
├── bunfig.toml          # Base config
├── bunfig.dev.toml      # Development overrides
├── bunfig.prod.toml     # Production overrides
└── package.json
```

```json package.json scripts theme={null}
{
  "scripts": {
    "dev": "cp bunfig.dev.toml bunfig.toml && bun run src/index.ts",
    "prod": "cp bunfig.prod.toml bunfig.toml && bun run src/index.ts"
  }
}
```

### Workspace Configuration

Configure for monorepos:

```toml Workspace bunfig.toml (root) theme={null}
[install]
workspace = true

[install.workspaces]
packages = ["packages/*"]
```

## Troubleshooting

### Config Not Loading

1. **Check file location**: Must be in project root or home directory
2. **Check file name**: Must be exactly `bunfig.toml`
3. **Check TOML syntax**: Use TOML validator
4. **Check permissions**: File must be readable

### Invalid Configuration

```bash theme={null}
error: Invalid Bunfig: Expected "registry" to be a URL string or an object
```

**Solution:** Check TOML syntax and field types.

### Registry Authentication

For private registries:

```toml Registry auth theme={null}
[install]
registry = "https://npm.company.com/"

# Or with token
[install.registry]
url = "https://npm.company.com/"
token = "npm_xxxxxxxxxxxx"
```

## Related

* [Environment Variables](/runtime/environment-variables) - Configure env loading
* [Loaders](/runtime/loaders) - File type configuration
* [Package Manager](/package-manager) - Install configuration