Configuration

Everything Bun reads to configure its own behaviour. This page is for contributors who need to change defaults or add a new option, not end-users.

Sources of truth, in priority order

1. CLI flags. Parsed in src/cli/Arguments.zig. Highest priority.
2. Env vars. Defined as a typed list in src/env_var.zig. Each bun.env_var.<NAME>.get() call is a documented read.
3. bunfig.toml. Project config. Loaded by src/bunfig.zig.
4. package.json. Anything Bun cares about — name, type, exports, imports, bun.* keys.
5. tsconfig.json. Path mapping and compiler options consulted by the resolver.

bunfig.toml

Section-by-section:

Section	Notes
[install]	Registry URL, auth, lockfile location, install strategy (hoisted vs isolated), savings of bunfig cache, auto install on missing imports.
[install.scopes]	Per-scope registry overrides (e.g. @my-org → private registry).
[install.lockfile]	Print kind, save text format.
[install.cache]	Cache directory, disable, lockfile reuse.
[run]	Default flags for bun run. GC tuning. Smol mode (--smol).
[test]	Coverage config, snapshot directory, default reporter.
[debug]	Debug-mode toggles (e.g. editor: "vscode" for bun --inspect-brk).
[serve]	Static defaults for bun.serve.
[loader]	Per-extension loader override (.bin = "file", etc.).
[define]	--define-style globals that get inlined.

Schema lives in src/bunfig.zig. Defaults come from each consumer (e.g. the package manager checks bun.bunfig.install at startup).

Typed env vars

src/env_var.zig declares every env var Bun reads. Each declaration includes:

• The expected type (bool, u64, []const u8, custom enum).
• A default.
• Optional aliases (e.g. NODE_OPTIONS is read for compat).
• A doc string (visible via bun --dump-environment-variables).

Adding a new env var:

1. Add the declaration to env_var.zig.
2. Read it via bun.env_var.MY_VAR.get() at the call site.
3. (Optional) Document it in bunfig.toml if it has a config-file equivalent.

A few of the most-used:

Variable	Use
BUN_DEBUG_<scope>	Enable a scoped logger.
BUN_DEBUG_QUIET_LOGS	Disable all debug logging.
BUN_JSC_validateExceptionChecks	Catch missing exception scope checks.
BUN_INSTALL	Override the install root for bun install.
BUN_CONFIG_DNS_TIME_TO_LIVE_SECONDS	DNS cache TTL (default 30).
NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, SSL_CERT_DIR	TLS root cert overrides.
BUN_RUNTIME_TRANSPILER_CACHE_PATH	Path for transpiler cache.
USE_SYSTEM_BUN	(test-only) run bun test against the system Bun rather than the debug build.

Run bun --dump-environment-variables to enumerate everything.

Runtime flags

A subset of high-impact flags. The full list is in Arguments.zig.

| Flag | Effect | | ---------------------------- | ---------------------------------------------------- | -------- | ----------------------------------- | | --watch / --hot | Enable runtime watch / HMR. | | --smol | Smaller heap, slower allocs, lower memory footprint. | | --inspect, --inspect-brk | Open the inspector on a port. | | --cpu-prof | Write a .cpuprofile for the run. | | --define K=V | Compile-time substitution. | | --conditions=a,b | Add conditions for module resolution. | | --target=bun | node | browser | Resolution + transformation target. | | --no-install | Disable auto-install. | | --silent | Suppress non-error output. |

package.json fields Bun reads

• name, version, type (module vs commonjs).
• main, module, browser, exports, imports.
• bin, files, workspaces, scripts.
• dependencies, devDependencies, peerDependencies, optionalDependencies, peerDependenciesMeta, bundleDependencies.
• engines.bun, engines.node.
• bun.* keys — Bun-specific options (e.g. bun.namespace overrides for the bundler).

tsconfig.json fields

The resolver reads:

• compilerOptions.baseUrl, paths.
• compilerOptions.jsx, jsxImportSource, jsxFactory, jsxFragmentFactory.
• extends (with multi-level inheritance).
• references (used to scope path resolution to declared subprojects).

The runtime additionally honours:

• compilerOptions.target (used to gate downlevel transforms in --target=bun mode).
• compilerOptions.experimentalDecorators.
• compilerOptions.useDefineForClassFields.

Source: src/resolver/tsconfig_json.zig.

Lockfile

The default is bun.lock — text JSONC, schema documented at the top of src/install/lockfile/. The legacy bun.lockb (binary) is still read for compat. See Package manager.

Where defaults live

Most defaults are inline const declarations in the consuming module. For widely-used defaults, look at:

• src/options.zig — bundler / resolver / runtime options.
• src/bunfig.zig — config defaults.
• src/bun.js/api/Bun.zig — runtime defaults exposed as Bun.*.
• src/install/PackageManager.zig — install defaults.