You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/runtime/bunfig.mdx
+242Lines changed: 242 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -115,6 +115,15 @@ Currently we do not collect telemetry and this setting is only used for enabling
115
115
telemetry = false
116
116
```
117
117
118
+
### `macros`
119
+
120
+
Configure Bun's macro behavior. Macros allow compile-time code execution. Set to `false` to disable macros entirely, or configure specific macro mappings.
121
+
122
+
```toml title="bunfig.toml" icon="settings"
123
+
# Disable macros
124
+
macros = false
125
+
```
126
+
118
127
### `env`
119
128
120
129
Configure automatic `.env` file loading. By default, Bun automatically loads `.env` files. To disable this behavior:
@@ -150,6 +159,93 @@ depth = 3
150
159
151
160
This controls how deeply nested objects are displayed in console output. Higher values show more nested properties but may produce verbose output for complex objects. This setting can be overridden by the `--console-depth` CLI flag.
152
161
162
+
## Serve
163
+
164
+
Configure the behavior of `bun --serve` under the `[serve]` section.
165
+
166
+
```toml title="bunfig.toml" icon="settings"
167
+
[serve]
168
+
# configuration goes here
169
+
```
170
+
171
+
### `serve.port`
172
+
173
+
Set the port number for the dev server. Default `3000`.
174
+
175
+
```toml title="bunfig.toml" icon="settings"
176
+
[serve]
177
+
port = 8080
178
+
```
179
+
180
+
### `serve.static`
181
+
182
+
Configure settings for static file serving and the dev server.
183
+
184
+
#### `serve.static.plugins`
185
+
186
+
Specify plugins to load for the dev server.
187
+
188
+
```toml title="bunfig.toml" icon="settings"
189
+
[serve.static]
190
+
plugins = ["./my-plugin.ts"]
191
+
```
192
+
193
+
#### `serve.static.hmr`
194
+
195
+
Enable or disable Hot Module Replacement. Default `true`.
196
+
197
+
```toml title="bunfig.toml" icon="settings"
198
+
[serve.static]
199
+
hmr = true
200
+
```
201
+
202
+
#### `serve.static.minify`
203
+
204
+
Configure minification settings. Can be a boolean to enable/disable all minification, or an object for fine-grained control.
Ignore sourcemaps when computing coverage statistics. This is primarily useful for debugging coverage issues. Default `false`.
360
+
361
+
```toml title="bunfig.toml" icon="settings"
362
+
[test]
363
+
coverageIgnoreSourcemaps = true
364
+
```
365
+
261
366
### `test.randomize`
262
367
263
368
Run tests in random order. Default `false`.
@@ -455,6 +560,50 @@ Whether `bun install` will actually install dependencies. Default `false`. When
455
560
dryRun = false
456
561
```
457
562
563
+
### `install.concurrentScripts`
564
+
565
+
Set the number of lifecycle scripts that can run concurrently during installation. This controls parallelism for `postinstall`, `preinstall`, and other scripts.
566
+
567
+
```toml title="bunfig.toml" icon="settings"
568
+
[install]
569
+
concurrentScripts = 4
570
+
```
571
+
572
+
### `install.ignoreScripts`
573
+
574
+
When `true`, skip running lifecycle scripts (`preinstall`, `postinstall`, etc.) during installation. Default `false`.
575
+
576
+
```toml title="bunfig.toml" icon="settings"
577
+
[install]
578
+
ignoreScripts = true
579
+
```
580
+
581
+
### `install.prefer`
582
+
583
+
Configure how Bun resolves package versions. Default behavior depends on network availability.
|`"online"`| Always fetch the latest versions from the registry. |
595
+
|`"offline"`| Use cached versions when available, without network requests. |
596
+
|`"latest"`| Prefer the latest versions, updating the lockfile as needed. |
597
+
598
+
### `install.logLevel`
599
+
600
+
Set the log level for package installation. This can be one of `"debug"`, `"warn"`, or `"error"`.
601
+
602
+
```toml title="bunfig.toml" icon="settings"
603
+
[install]
604
+
logLevel = "warn"
605
+
```
606
+
458
607
### `install.globalDir`
459
608
460
609
To configure the directory where Bun puts globally installed packages.
@@ -570,6 +719,20 @@ Whether to generate a non-Bun lockfile alongside `bun.lock`. (A `bun.lock` will
570
719
print = "yarn"
571
720
```
572
721
722
+
Specify a custom path to read the lockfile from:
723
+
724
+
```toml title="bunfig.toml" icon="settings"
725
+
[install.lockfile]
726
+
path = "./custom/bun.lock"
727
+
```
728
+
729
+
Specify a custom path to save the lockfile to:
730
+
731
+
```toml title="bunfig.toml" icon="settings"
732
+
[install.lockfile]
733
+
savePath = "./custom/bun.lock"
734
+
```
735
+
573
736
### `install.linker`
574
737
575
738
Configure the linker strategy for installing dependencies. Defaults to `"isolated"` for new workspaces, `"hoisted"` for new single-package projects and existing projects (made pre-v1.3.2).
@@ -588,6 +751,28 @@ Valid values are:
588
751
|`"hoisted"`| Link dependencies in a shared `node_modules` directory. |
589
752
|`"isolated"`| Link dependencies inside each package installation. |
590
753
754
+
### `install.hoistPattern`
755
+
756
+
Specify glob patterns for packages that should be hoisted to the root `node_modules`. This is similar to pnpm's `hoist-pattern` option. Only applies when using `linker = "isolated"`.
757
+
758
+
```toml title="bunfig.toml" icon="settings"
759
+
[install]
760
+
hoistPattern = ["*"]
761
+
```
762
+
763
+
### `install.publicHoistPattern`
764
+
765
+
Specify glob patterns for packages that should be publicly hoisted (accessible to all packages). This is similar to pnpm's `public-hoist-pattern` option. Only applies when using `linker = "isolated"`.
766
+
767
+
```toml title="bunfig.toml" icon="settings"
768
+
[install]
769
+
publicHoistPattern = ["*eslint*", "*prettier*"]
770
+
```
771
+
772
+
## Debug
773
+
774
+
Configure debugging options under the `[debug]` section.
775
+
591
776
```toml title="bunfig.toml" icon="settings"
592
777
[debug]
593
778
# When navigating to a blob: or src: link, open the file in your editor
@@ -741,3 +926,60 @@ bun --silent run dev
741
926
bun --silent dev
742
927
bun run --silent dev
743
928
```
929
+
930
+
### `run.elide-lines`
931
+
932
+
Set the number of lines to elide (hide) in error output. This can help reduce noise in stack traces by truncating very long output.
933
+
934
+
```toml title="bunfig.toml" icon="settings"
935
+
[run]
936
+
elide-lines = 10
937
+
```
938
+
939
+
## Bundle
940
+
941
+
Configure bundler settings under the `[bundle]` section. These options apply to `bun build`.
Set the log level for the bundler. This can be one of `"debug"`, `"warn"`, or `"error"`.
969
+
970
+
```toml title="bunfig.toml" icon="settings"
971
+
[bundle]
972
+
logLevel = "warn"
973
+
```
974
+
975
+
### `bundle.packages`
976
+
977
+
Configure how specific packages should be handled during bundling. Set a package to `true` to always bundle it, or `false` to always mark it as external.
978
+
979
+
```toml title="bunfig.toml" icon="settings"
980
+
[bundle.packages]
981
+
# Always bundle lodash, even if it's in node_modules
0 commit comments