From d4eaaf83636d80a111f8565532ffc4a6ee95370e Mon Sep 17 00:00:00 2001
From: robobun <robobun@oven.sh>
Date: Sun, 7 Dec 2025 15:44:06 -0800
Subject: [PATCH] docs: document autoload options for standalone executables
 (#25385)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 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>
---
 docs/bundler/executables.mdx | 41 ++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/docs/bundler/executables.mdx b/docs/bundler/executables.mdx
index 651c3ce7d8..50d1a7cafd 100644
--- a/docs/bundler/executables.mdx
+++ b/docs/bundler/executables.mdx
@@ -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
   },