# bunfig.toml > Configure Bun's behavior using its configuration file bunfig.toml `bunfig.toml` is Bun's configuration file. Bun relies on pre-existing configuration files like `package.json` and `tsconfig.json` where it can; `bunfig.toml` is only for Bun-specific settings. The file is optional, and Bun works without it. ## Global vs. local Put `bunfig.toml` in your project root, alongside your `package.json`. To configure Bun's package manager globally, you can also create a `.bunfig.toml` file at one of the following paths: - `$HOME/.bunfig.toml` - `$XDG_CONFIG_HOME/.bunfig.toml` Only package manager commands (`bun install`, `bun add`, `bun remove`, `bun update`, `bun pm`, `bunx`, and so on) read the global file. If Bun finds both a global and a local `bunfig`, it loads both; keys set in the local file override the same keys in the global file. CLI flags override `bunfig` settings where applicable. ## Runtime Top-level fields in `bunfig.toml` configure Bun's runtime behavior. ### `preload` An array of scripts/plugins to execute before running a file or script. ```toml title="bunfig.toml" icon="settings" # scripts to run before `bun run`-ing a file or script # register plugins by adding them to this list preload = ["./preload.ts"] ``` ### `jsx` Configure how Bun handles JSX. You can also set these fields in the `compilerOptions` of your `tsconfig.json`, but `bunfig.toml` supports them for non-TypeScript projects. ```toml title="bunfig.toml" icon="settings" 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 title="bunfig.toml" icon="settings" # Reduce memory usage at the cost of performance smol = true ``` ### `logLevel` Set the log level: `"debug"`, `"warn"`, or `"error"`. ```toml title="bunfig.toml" icon="settings" logLevel = "debug" # "debug" | "warn" | "error" ``` ### `define` The `define` field replaces global identifiers with constant expressions wherever they appear. The expression should be a JSON string. ```toml title="bunfig.toml" icon="settings" [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](https://aphrody.app/docs/bundler/loaders). Use this to load file types Bun doesn't support natively. ```toml title="bunfig.toml" icon="settings" [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` ### `telemetry` The `telemetry` field enables or disables analytics. By default, telemetry is enabled. This setting is equivalent to the `DO_NOT_TRACK` environment variable. We do not currently collect telemetry; this setting only controls anonymous crash reports. We plan to collect information like which Bun APIs are used most or how long `bun build` takes. ```toml title="bunfig.toml" icon="settings" telemetry = false ``` ### `env` Configure automatic `.env` file loading. Bun loads `.env` files by default. To disable this behavior: ```toml title="bunfig.toml" icon="settings" # Disable automatic .env file loading env = false ``` You can also use object syntax with the `file` property: ```toml title="bunfig.toml" icon="settings" [env] file = false ``` Use this in production or CI/CD pipelines where you want to rely solely on system environment variables. Bun still loads files passed explicitly with `--env-file` even when default loading is disabled. ### `console` Configure console output behavior. #### `console.depth` Set the default depth for `console.log()` object inspection. Default `2`. ```toml title="bunfig.toml" icon="settings" [console] depth = 3 ``` Higher values show more nested properties but may produce verbose output for complex objects. The `--console-depth` CLI flag overrides this setting. ## Serve The `[serve]` section configures `Bun.serve` and `bun run` when serving HTTP. ### `serve.port` The default port for `Bun.serve` to listen on. Default `3000`. You can also set it with the `BUN_PORT` or `PORT` environment variables, or the `--port` flag. ```toml title="bunfig.toml" icon="settings" [serve] port = 3000 ``` ## Lint and format [`bun lint`](https://aphrody.app/docs/runtime/lint) and [`bun fmt`](https://aphrody.app/docs/runtime/fmt) run their linked native engines. They do not use `[lint]` or `[fmt]` sections to select executables, versions or downloads. Use `.oxlintrc.json` or `.oxlintrc.jsonc` for lint rules, and `.oxfmtrc.json` or `.oxfmtrc.jsonc` for formatting options. Pass `--config` for an explicit configuration, filesystem operands for scope and `--ignore-pattern` for exclusions. ```sh bun lint --config .oxlintrc.json src bun fmt --config .oxfmtrc.json --check src ``` ## Test runner The `[test]` section of `bunfig.toml` configures the test runner. ```toml title="bunfig.toml" icon="settings" [test] # configuration goes here ``` ### `test.root` The root directory to run tests from. Default `.`. ```toml title="bunfig.toml" icon="settings" [test] root = "./__tests__" ``` ### `test.preload` Same as the top-level `preload` field, but only applies to `bun test`. ```toml title="bunfig.toml" icon="settings" [test] preload = ["./setup.ts"] ``` ### `test.pathIgnorePatterns` Exclude files and directories from test discovery using glob patterns. The test runner prunes matched directories during scanning, so it never traverses their contents. Use this when your project contains submodules or vendored code with `*.test.ts` files that you don't want `bun test` to pick up. ```toml title="bunfig.toml" icon="settings" [test] pathIgnorePatterns = ["vendor/**", "submodules/**", "fixtures/**"] ``` Equivalent CLI flag: `--path-ignore-patterns`. CLI flags override the `bunfig.toml` value entirely. ### `test.snapshotSerializers` Modules whose default export (or the module itself) is a Jest/Vitest snapshot serializer, an object with `test()` and either `serialize()` or `print()`. They load after `test.preload` and are registered as if passed to `expect.addSnapshotSerializer()`. Paths resolve like `test.preload`. ```toml title="bunfig.toml" icon="settings" [test] snapshotSerializers = ["./test/serializers/date.ts"] ``` ### `test.smol` Same as the top-level `smol` field, but only applies to `bun test`. ```toml title="bunfig.toml" icon="settings" [test] smol = true ``` ### `test.coverage` Enables coverage reporting. Default `false`. Use `--coverage` to override. ```toml title="bunfig.toml" icon="settings" [test] coverage = false ``` ### `test.coverageThreshold` The coverage threshold. By default, no threshold is set. If your test suite does not meet it, `bun test` exits with a non-zero exit code. ```toml title="bunfig.toml" icon="settings" [test] # to require 90% line-level and function-level coverage coverageThreshold = 0.9 ``` You can set separate thresholds for line and function coverage. Bun accepts a `statements` key but does not currently enforce it. ```toml title="bunfig.toml" icon="settings" [test] coverageThreshold = { lines = 0.7, functions = 0.8 } ``` ### `test.coverageSkipTestFiles` Whether to skip test files when computing coverage statistics. Default `false`. ```toml title="bunfig.toml" icon="settings" [test] coverageSkipTestFiles = false ``` ### `test.coverageIgnoreSourcemaps` Whether to report coverage against transpiled output instead of remapping line numbers through sourcemaps back to the original source. Default `false`. Primarily useful for debugging. ```toml title="bunfig.toml" icon="settings" [test] coverageIgnoreSourcemaps = false ``` ### `test.coveragePathIgnorePatterns` Exclude files from coverage reports using glob patterns. Accepts a single pattern or an array of patterns. ```toml title="bunfig.toml" icon="settings" [test] # Single pattern coveragePathIgnorePatterns = "**/*.spec.ts" # Multiple patterns coveragePathIgnorePatterns = [ "**/*.spec.ts", "**/*.test.ts", "src/utils/**", "*.config.js" ] ``` ### `test.coverageReporter` By default, the test runner prints coverage reports to the console. For persistent reports that CI and other tools can read, use `lcov`. ```toml title="bunfig.toml" icon="settings" [test] coverageReporter = ["text", "lcov"] # default ["text"] ``` ### `test.coverageDir` Set the path where coverage reports are saved. This only applies to persistent reporters like `lcov`. ```toml title="bunfig.toml" icon="settings" [test] coverageDir = "path/to/somewhere" # default "coverage" ``` ### `test.randomize` Run tests in random order. Default `false`. ```toml title="bunfig.toml" icon="settings" [test] randomize = true ``` Running tests in a different order each time helps catch bugs related to test interdependencies. When combined with `seed`, the random order becomes reproducible. The `--randomize` CLI flag overrides this setting. ### `test.seed` Set the random seed for test randomization. This option requires `randomize` to be `true`. ```toml title="bunfig.toml" icon="settings" [test] randomize = true seed = 2444615283 ``` A seed makes the randomized test order reproducible across runs, which helps when debugging flaky tests. The `--seed` CLI flag overrides this setting. ### `test.rerunEach` Re-run each test file a specified number of times. Default `0` (run once). ```toml title="bunfig.toml" icon="settings" [test] rerunEach = 3 ``` Use this to catch flaky tests or non-deterministic behavior. The `--rerun-each` CLI flag overrides this setting. ### `test.retry` Default retry count for all tests. The test runner retries failed tests up to this many times. Per-test `{ retry: N }` overrides this value. Default `0` (no retries). ```toml title="bunfig.toml" icon="settings" [test] retry = 3 ``` The `--retry` CLI flag overrides this setting. ### `test.concurrentTestGlob` Test files matching this glob pattern run all of their tests concurrently, as if you passed the `--concurrent` flag. ```toml title="bunfig.toml" icon="settings" [test] concurrentTestGlob = "**/concurrent-*.test.ts" ``` Use this to migrate a test suite to concurrent execution gradually, or to run integration tests concurrently while keeping unit tests sequential. The `--concurrent` CLI flag overrides this setting. ### `test.onlyFailures` When enabled, the output shows only failed tests, which reduces noise in large test suites. Default `false`. ```toml title="bunfig.toml" icon="settings" [test] onlyFailures = true ``` Equivalent to the `--only-failures` flag. ### `test.reporter` Configure the test reporter settings. #### `test.reporter.dots` Enable the dots reporter, which prints one dot per test. Default `false`. ```toml title="bunfig.toml" icon="settings" [test.reporter] dots = true ``` #### `test.reporter.junit` Enable JUnit XML reporting and specify the output file path. ```toml title="bunfig.toml" icon="settings" [test.reporter] junit = "test-results.xml" ``` CI systems and other tools can consume the report. ## Linter The `[lint]` section configures [`bun lint`](https://aphrody.app/docs/lint). Run `bun lint --init` to add it. ```toml title="bunfig.toml" icon="settings" [lint] typeAware = true ignorePatterns = ["vendor/", "**/*.gen.ts"] [lint.rules] "no-console" = "warn" eqeqeq = ["error", "smart"] [[lint.overrides]] files = ["scripts/**"] rules = { "no-console" = "off" } ``` `bun lint` uses the nearest `bunfig.toml` that has a `[lint]` section, from the working directory up, so it finds the same problems from any directory of the project. Next to an ESLint or oxlint config, what those tools read from the working directory is still read from there. Paths and patterns in the section are relative to the file, including the ones in the options of the `import` rules. So are the patterns in a config file that `config` names and the file names in the file that `suppressionsLocation` names. With `bun --config= lint`, everything but `plugins` is relative to the working directory. A typo is an error. `bun lint` exits with code `2` on an unknown key or an unknown rule. ```txt 2 | "no-vra" = "error" ^ error: Unknown rule "no-vra" Did you mean "no-var"? at bunfig.toml:2:1 ``` ### `lint.rules` Set a rule to `"off"`, `"warn"`, or `"error"`. To pass options, use an array. Every rule in `bun lint --rules` works, with nothing to install. ```toml title="bunfig.toml" icon="settings" [lint.rules] "no-console" = "warn" "@typescript-eslint/no-explicit-any" = "off" "unicorn/prefer-node-protocol" = "error" "no-restricted-imports" = ["error", { paths = ["lodash"] }] ``` Some ESLint rules have a typescript-eslint version, such as `no-unused-vars` and `@typescript-eslint/no-unused-vars`. Setting either name sets both. The ESLint rule runs on JavaScript files and the typescript-eslint rule on TypeScript files, so a problem is never reported twice. If you set both names, each one applies to its own kind of file. A few typescript-eslint versions need type information, such as `@typescript-eslint/require-await`. Setting that name type checks your TypeScript files, like any other [type-aware rule](https://aphrody.app/docs/lint#type-aware-rules). Setting only `require-await` doesn't start a type check. It uses the typescript-eslint version if the run has types anyway, and the ESLint rule otherwise. ### `lint.plugins` Load [ESLint plugins](https://aphrody.app/docs/lint/plugins): paths, relative to `bunfig.toml`, or package names. Their rules are added to the built-in ones. ```toml title="bunfig.toml" icon="settings" [lint] plugins = ["./lint/plugin.js", "eslint-plugin-perfectionist"] [lint.rules] "local/no-todo" = "warn" "perfectionist/sort-imports" = "error" ``` ### `lint.categories` Set a whole category of rules at once. `[lint.rules]` wins over a category. ```toml title="bunfig.toml" icon="settings" [lint.categories] suspicious = "warn" perf = "warn" ``` | Category | What its rules report | | ------------- | ---------------------------------------------- | | `correctness` | Code that is wrong or useless | | `suspicious` | Code that is probably wrong or useless | | `pedantic` | Strict checks, with some false positives | | `perf` | Code that could run faster | | `style` | Code that could be more idiomatic | | `restriction` | Language features and patterns you want to ban | | `nursery` | New rules that are still changing | | `all` | Every category at once | ### `lint.overrides` Use different rules for some files. `files` is required. `excludeFiles`, `rules`, `globals`, and `settings` are optional. ```toml title="bunfig.toml" icon="settings" [[lint.overrides]] files = ["*.test.ts", "scripts/**"] excludeFiles = ["scripts/vendor/**"] rules = { "no-console" = "off" } ``` Patterns use the same syntax as [`Bun.Glob`](https://aphrody.app/docs/runtime/glob) and are relative to `bunfig.toml`. A pattern without a slash matches the file name in any directory. Later overrides win over earlier ones, and all of them win over `[lint.rules]`. ### `lint.ignorePatterns` Skip the files that match. `bun lint` already skips `node_modules` and everything in `.gitignore`. ```toml title="bunfig.toml" icon="settings" [lint] ignorePatterns = ["vendor/", "**/*.gen.ts"] ``` ### `lint.settings` Settings that rules share, such as the React version. The same as `settings` in an ESLint or oxlint config. ```toml title="bunfig.toml" icon="settings" [lint.settings.react] version = "18.2" [lint.settings."jsx-a11y".components] Picture = "img" ``` ### `lint.typeAware` Turn on typescript-eslint's recommended [type-aware rules](https://aphrody.app/docs/lint#type-aware-rules), such as `@typescript-eslint/no-floating-promises`. Default `false`. ```toml title="bunfig.toml" icon="settings" [lint] typeAware = true tsconfig = "./tsconfig.lint.json" # default: the nearest tsconfig.json ``` You don't need it for a single rule. A type-aware rule runs as soon as you turn it on in `[lint.rules]`. `typeAware = false` skips every type-aware rule. ### `lint.typeCheck` Also report type errors, like [`bun check`](https://aphrody.app/docs/runtime/check). It turns on no rules. Default `false`. ```toml title="bunfig.toml" icon="settings" [lint] typeCheck = true ``` ### `lint.globals` Declare global variables, so that `no-undef` accepts them. A global is `"readonly"`, `"writable"`, or `"off"`. ```toml title="bunfig.toml" icon="settings" [lint.globals] MY_GLOBAL = "readonly" ``` ### `lint.maxWarnings` Exit with code `1` if there are more warnings than this. By default, warnings never fail a run. ```toml title="bunfig.toml" icon="settings" [lint] maxWarnings = 0 ``` ### All keys Every flag that makes sense as a default is also a key, in camelCase: `--max-warnings 0` is `maxWarnings = 0`, and `--no-inline-config` is `inlineConfig = false`. The command line wins over `bunfig.toml`. | Key | Value | Flag | | ------------------------------- | ------------------------------------- | --------------------------------------------------- | | `rules` | table | `--rule` | | `plugins` | array | `--plugin` | | `categories` | table | `-A`, `-W`, `-D` | | `overrides` | array of tables | | | `globals` | table | `--global` | | `settings` | table | | | `ignorePatterns` | array | `--ignore-pattern` | | `typeAware` | boolean | `--type-aware`, `--no-type-aware` | | `typeCheck` | boolean | `--type-check` | | `tsconfig` | path | `--tsconfig` | | `inferGlobals` | boolean | `--infer-globals`, `--no-infer-globals` | | `maxWarnings` | number | `--max-warnings` | | `denyWarnings` | boolean | `--deny-warnings` | | `quiet` | boolean | `--quiet` | | `silent` | boolean | `--silent` | | `format` | name | `-f`, `--format` | | `all` | boolean | `--all` | | `threads` | number | `--threads` | | `inlineConfig` | boolean | `--no-inline-config` | | `reportUnusedDisableDirectives` | boolean, `"off"`, `"warn"`, `"error"` | `--report-unused-disable-directives` | | `reportUnusedInlineConfigs` | `"off"`, `"warn"`, `"error"` | `--report-unused-inline-configs` | | `fixType` | array | `--fix-type` | | `config` | path | `-c`, `--config` | | `configLookup` | boolean | `--no-config-lookup` | | `disableNestedConfig` | boolean | `--disable-nested-config` | | `allowUnsupported` | boolean | `--allow-unsupported` | | `nativePluginRules` | boolean, or an array of plugin names | `--native-plugin-rules`, `--no-native-plugin-rules` | | `parserOptions` | table | `--parser-options` | | `ext` | array | `--ext` | | `ignore` | boolean | `--no-ignore` | | `ignorePath` | path | `--ignore-path` | | `warnIgnored` | boolean | `--no-warn-ignored` | | `errorOnUnmatchedPattern` | boolean | `--no-error-on-unmatched-pattern` | | `passOnNoPatterns` | boolean | `--pass-on-no-patterns` | | `exitOnFatalError` | boolean | `--exit-on-fatal-error` | | `suppressionsLocation` | path | `--suppressions-location` | | `passOnUnprunedSuppressions` | boolean | `--pass-on-unpruned-suppressions` | `bun lint --help --all` says what each flag does. `[lint]` also applies next to an `eslint.config.js` or an `.oxlintrc.json`. There, a key overrides the config file the way its flag does. ## Formatter The `[fmt]` section configures [`bun fmt`](https://aphrody.app/docs/format). Run `bun fmt --init` to add it. ```toml title="bunfig.toml" icon="settings" [fmt] printWidth = 100 semi = false sortImports = true ignorePatterns = ["vendor/", "**/*.gen.ts"] ``` `bun fmt` uses the nearest `bunfig.toml` that has a `[fmt]` section, from the working directory up, so it prints the same from any directory of the project. Paths and patterns in the section are relative to the file. With `bun --config= fmt` they are relative to the working directory. A typo doesn't go unnoticed. An unknown key or a bad value is an error, and `bun fmt` exits with code `2`. ### Style options Same names, defaults, and meaning as [Prettier's options](https://prettier.io/docs/options). Each one is also a flag, like `--print-width 100` or `--no-semi`, and the flag wins. | Key | Default | What it does | | ------------------------------ | ------------- | --------------------------------------------------------------------- | | `printWidth` | `80` | Wrap lines at this column | | `tabWidth` | `2` | Spaces per indentation level | | `useTabs` | `false` | Indent with tabs | | `semi` | `true` | Print semicolons | | `singleQuote` | `false` | Use single quotes | | `jsxSingleQuote` | `false` | Use single quotes in JSX | | `quoteProps` | `"as-needed"` | Quote object keys: `"as-needed"`, `"consistent"`, or `"preserve"` | | `trailingComma` | `"all"` | `"all"`, `"es5"`, or `"none"` | | `bracketSpacing` | `true` | `{ a }` or `{a}` | | `bracketSameLine` | `false` | Put the `>` of a multi-line element at the end of the last line | | `arrowParens` | `"always"` | `(x) => x` or, with `"avoid"`, `x => x` | | `objectWrap` | `"preserve"` | `"collapse"` puts an object on one line whenever it fits | | `singleAttributePerLine` | `false` | One attribute per line in HTML, Vue, and JSX | | `proseWrap` | `"preserve"` | Wrap Markdown text: `"always"`, `"never"`, or `"preserve"` | | `endOfLine` | `"lf"` | `"lf"`, `"crlf"`, `"cr"`, or `"auto"` | | `htmlWhitespaceSensitivity` | `"css"` | How whitespace in HTML is treated: `"css"`, `"strict"`, or `"ignore"` | | `vueIndentScriptAndStyle` | `false` | Indent the code in `