mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
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 <claude-bot@bun.sh> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
This commit is contained in:
@@ -183,9 +183,35 @@ console.log(process.execArgv); // ["--smol", "--user-agent=MyBot"]
|
||||
|
||||
---
|
||||
|
||||
## Disabling automatic config loading
|
||||
## Automatic config loading
|
||||
|
||||
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.
|
||||
Standalone executables can automatically load configuration files from the directory where they are run. By default:
|
||||
|
||||
- **`tsconfig.json`** and **`package.json`** loading is **disabled** — these are typically only needed at development time, and the bundler already uses them when compiling
|
||||
- **`.env`** and **`bunfig.toml`** loading is **enabled** — these often contain runtime configuration that may vary per deployment
|
||||
|
||||
<Note>
|
||||
In a future version of Bun, `.env` and `bunfig.toml` may also be disabled by default for more deterministic behavior.
|
||||
</Note>
|
||||
|
||||
### Enabling config loading at runtime
|
||||
|
||||
If your executable needs to read `tsconfig.json` or `package.json` at runtime, you can opt in with the new CLI flags:
|
||||
|
||||
```bash icon="terminal" terminal
|
||||
# Enable runtime loading of tsconfig.json
|
||||
bun build --compile --compile-autoload-tsconfig ./app.ts --outfile myapp
|
||||
|
||||
# Enable runtime loading of package.json
|
||||
bun build --compile --compile-autoload-package-json ./app.ts --outfile myapp
|
||||
|
||||
# Enable both
|
||||
bun build --compile --compile-autoload-tsconfig --compile-autoload-package-json ./app.ts --outfile myapp
|
||||
```
|
||||
|
||||
### Disabling config loading at runtime
|
||||
|
||||
To disable `.env` or `bunfig.toml` loading for deterministic execution:
|
||||
|
||||
```bash icon="terminal" terminal
|
||||
# Disable .env loading
|
||||
@@ -194,16 +220,23 @@ bun build --compile --no-compile-autoload-dotenv ./app.ts --outfile myapp
|
||||
# Disable bunfig.toml loading
|
||||
bun build --compile --no-compile-autoload-bunfig ./app.ts --outfile myapp
|
||||
|
||||
# Disable both
|
||||
# Disable all config loading
|
||||
bun build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig ./app.ts --outfile myapp
|
||||
```
|
||||
|
||||
You can also configure this via the JavaScript API:
|
||||
### JavaScript API
|
||||
|
||||
You can also configure autoloading via the JavaScript API:
|
||||
|
||||
```ts
|
||||
await Bun.build({
|
||||
entrypoints: ["./app.ts"],
|
||||
compile: {
|
||||
// tsconfig.json and package.json are disabled by default
|
||||
autoloadTsconfig: true, // Enable tsconfig.json loading
|
||||
autoloadPackageJson: true, // Enable package.json loading
|
||||
|
||||
// .env and bunfig.toml are enabled by default
|
||||
autoloadDotenv: false, // Disable .env loading
|
||||
autoloadBunfig: false, // Disable bunfig.toml loading
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user