Skip to content

Commit d4eaaf8

Browse files
robobunClaude Botclaudeautofix-ci[bot]
authored
docs: document autoload options for standalone executables (#25385)
## Summary - Document new default behavior in v1.3.4: `tsconfig.json` and `package.json` loading is now disabled by default for standalone executables - Add documentation for `--compile-autoload-tsconfig` and `--compile-autoload-package-json` CLI flags - Document all four JavaScript API options: `autoloadTsconfig`, `autoloadPackageJson`, `autoloadDotenv`, `autoloadBunfig` - Note that `.env` and `bunfig.toml` may also be disabled by default in a future version ## Test plan - [ ] Review rendered documentation for accuracy and formatting 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Bot <[email protected]> Co-authored-by: Claude <[email protected]> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
1 parent e1aa437 commit d4eaaf8

File tree

1 file changed

+37
-4
lines changed

1 file changed

+37
-4
lines changed

docs/bundler/executables.mdx

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -183,9 +183,35 @@ console.log(process.execArgv); // ["--smol", "--user-agent=MyBot"]
183183

184184
---
185185

186-
## Disabling automatic config loading
186+
## Automatic config loading
187187

188-
By default, standalone executables look for `.env` and `bunfig.toml` files in the directory where the executable is run. You can disable this behavior at build time for deterministic execution regardless of the user's working directory.
188+
Standalone executables can automatically load configuration files from the directory where they are run. By default:
189+
190+
- **`tsconfig.json`** and **`package.json`** loading is **disabled** — these are typically only needed at development time, and the bundler already uses them when compiling
191+
- **`.env`** and **`bunfig.toml`** loading is **enabled** — these often contain runtime configuration that may vary per deployment
192+
193+
<Note>
194+
In a future version of Bun, `.env` and `bunfig.toml` may also be disabled by default for more deterministic behavior.
195+
</Note>
196+
197+
### Enabling config loading at runtime
198+
199+
If your executable needs to read `tsconfig.json` or `package.json` at runtime, you can opt in with the new CLI flags:
200+
201+
```bash icon="terminal" terminal
202+
# Enable runtime loading of tsconfig.json
203+
bun build --compile --compile-autoload-tsconfig ./app.ts --outfile myapp
204+
205+
# Enable runtime loading of package.json
206+
bun build --compile --compile-autoload-package-json ./app.ts --outfile myapp
207+
208+
# Enable both
209+
bun build --compile --compile-autoload-tsconfig --compile-autoload-package-json ./app.ts --outfile myapp
210+
```
211+
212+
### Disabling config loading at runtime
213+
214+
To disable `.env` or `bunfig.toml` loading for deterministic execution:
189215

190216
```bash icon="terminal" terminal
191217
# Disable .env loading
@@ -194,16 +220,23 @@ bun build --compile --no-compile-autoload-dotenv ./app.ts --outfile myapp
194220
# Disable bunfig.toml loading
195221
bun build --compile --no-compile-autoload-bunfig ./app.ts --outfile myapp
196222

197-
# Disable both
223+
# Disable all config loading
198224
bun build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig ./app.ts --outfile myapp
199225
```
200226

201-
You can also configure this via the JavaScript API:
227+
### JavaScript API
228+
229+
You can also configure autoloading via the JavaScript API:
202230

203231
```ts
204232
await Bun.build({
205233
entrypoints: ["./app.ts"],
206234
compile: {
235+
// tsconfig.json and package.json are disabled by default
236+
autoloadTsconfig: true, // Enable tsconfig.json loading
237+
autoloadPackageJson: true, // Enable package.json loading
238+
239+
// .env and bunfig.toml are enabled by default
207240
autoloadDotenv: false, // Disable .env loading
208241
autoloadBunfig: false, // Disable bunfig.toml loading
209242
},

0 commit comments

Comments
 (0)