docs: document autoload options for standalone executables

[robobun]

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

[robobun]

^{Updated 10:21 PM PT - Dec 6th, 2025}

✅ @autofix-ci[bot], your commit b1ab4b12e6e96b28550746b1abd675fb447bfecb passed in Build #32977! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 25385

That installs a local version of the PR into your bun-25385 executable, so you can run:

bun-25385 --bun

[coderabbitai]

Walkthrough

This PR updates documentation in docs/bundler/executables.mdx to describe automatic config loading behavior during bundling. It renames sections, clarifies default loading behavior for different config files, and documents new CLI flags (--compile-autoload-tsconfig, --compile-autoload-package-json, --no-compile-autoload-dotenv, --no-compile-autoload-bunfig) and JavaScript API options for controlling autoload behavior at runtime.

Changes

Cohort / File(s)

Summary

Config loading documentation docs/bundler/executables.mdx

Renames "Disabling automatic config loading" section to "Automatic config loading". Rewrites content to describe default autoload behavior (tsconfig.json and package.json disabled during bundling; .env and bunfig.toml enabled at runtime). Adds new "Enabling config loading at runtime" and "Disabling config loading at runtime" sections with CLI flag examples. Updates JavaScript API examples to show new compile.autoload configuration options.

Possibly related PRs

• #24932 — Documents compile-time/runtime autoload flags for disabling .env and bunfig.toml behavior in the executables documentation.
• #25340 — Implements the new runtime autoload defaults and CLI/JavaScript API flags for controlling tsconfig.json, package.json, .env, and bunfig.toml loading.

Suggested reviewers

• lydiahallie
• RiskyMH

Pre-merge checks

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: documenting autoload options for standalone executables, which aligns with the core objective of the PR.
Description check	✅ Passed	The PR description covers the required template sections with specific details about what is documented, but the test plan checkbox is unchecked and lacks actual verification details.

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between b80cb62 and b1ab4b1.

📒 Files selected for processing (1)

• docs/bundler/executables.mdx (2 hunks)

🧰 Additional context used

🧠 Learnings (12)

📓 Common learnings

Learnt from: RiskyMH
Repo: oven-sh/bun PR: 24719
File: docs/bundler/executables.mdx:527-560
Timestamp: 2025-11-14T16:07:01.064Z
Learning: In the Bun repository, certain bundler features like compile with code splitting (--compile --splitting) are CLI-only and not supported in the Bun.build() JavaScript API. Tests for CLI-only features use backend: "cli" flag (e.g., test/bundler/bundler_compile_splitting.test.ts). The CompileBuildConfig interface correctly restricts these with splitting?: never;. When documenting CLI-only bundler features, add a note clarifying they're not available via the programmatic API.

Learnt from: RiskyMH
Repo: oven-sh/bun PR: 25111
File: packages/bun-types/wasm.d.ts:103-104
Timestamp: 2025-11-27T15:18:21.607Z
Learning: In the Bun repository, autofixci automatically formats code in the main branch, which can cause formatting diffs to appear in pull requests even when the PR author didn't make those changes. These formatting changes from autofixci are expected and not the PR author's responsibility.

📚 Learning: 2025-11-14T16:07:01.064Z

Learnt from: RiskyMH
Repo: oven-sh/bun PR: 24719
File: docs/bundler/executables.mdx:527-560
Timestamp: 2025-11-14T16:07:01.064Z
Learning: In the Bun repository, certain bundler features like compile with code splitting (--compile --splitting) are CLI-only and not supported in the Bun.build() JavaScript API. Tests for CLI-only features use backend: "cli" flag (e.g., test/bundler/bundler_compile_splitting.test.ts). The CompileBuildConfig interface correctly restricts these with splitting?: never;. When documenting CLI-only bundler features, add a note clarifying they're not available via the programmatic API.

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-10-19T02:52:37.412Z

Learnt from: theshadow27
Repo: oven-sh/bun PR: 23798
File: packages/bun-otel/tsconfig.json:1-15
Timestamp: 2025-10-19T02:52:37.412Z
Learning: In the Bun repository, packages under packages/ (e.g., bun-otel) can follow a TypeScript-first pattern where package.json exports point directly to .ts files (not compiled .js files). Bun natively runs TypeScript, so consumers import .ts sources directly and receive full type information without needing compiled .d.ts declaration files. For such packages, adding "declaration": true or "outDir" in tsconfig.json is unnecessary and would break the export structure.
<!-- [remove_learning]
ceedde95-980e-4898-a2c6-40ff73913664

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-11-24T18:37:30.259Z

Learnt from: CR
Repo: oven-sh/bun PR: 0
File: test/CLAUDE.md:0-0
Timestamp: 2025-11-24T18:37:30.259Z
Learning: Applies to test/**/*.test.{ts,js,jsx,tsx,mjs,cjs} : When spawning Bun processes in tests, use `bunExe` and `bunEnv` from `harness` to ensure the same build of Bun is used and debug logging is silenced

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-11-24T18:34:55.173Z

Learnt from: CR
Repo: oven-sh/bun PR: 0
File: .cursor/rules/building-bun.mdc:0-0
Timestamp: 2025-11-24T18:34:55.173Z
Learning: Applies to src/**/*.{cpp,zig} : Execute files using `bun bd <file> <...args>`; never use `bun <file>` directly as it will not include your changes

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-11-24T18:35:50.422Z

Learnt from: CR
Repo: oven-sh/bun PR: 0
File: .cursor/rules/writing-tests.mdc:0-0
Timestamp: 2025-11-24T18:35:50.422Z
Learning: Applies to test/cli/**/*.{js,ts,jsx,tsx} : When testing Bun as a CLI, use the `spawn` API from `bun` with the `bunExe()` and `bunEnv` from `harness` to execute Bun commands and validate exit codes, stdout, and stderr

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-10-26T01:32:04.844Z

Learnt from: Jarred-Sumner
Repo: oven-sh/bun PR: 24082
File: test/cli/test/coverage.test.ts:60-112
Timestamp: 2025-10-26T01:32:04.844Z
Learning: In the Bun repository test files (test/cli/test/*.test.ts), when spawning Bun CLI commands with Bun.spawnSync for testing, prefer using stdio: ["inherit", "inherit", "inherit"] to inherit stdio streams rather than piping them.

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-11-24T18:37:30.259Z

Learnt from: CR
Repo: oven-sh/bun PR: 0
File: test/CLAUDE.md:0-0
Timestamp: 2025-11-24T18:37:30.259Z
Learning: Applies to test/**/*.test.{ts,js,jsx,tsx,mjs,cjs} : Use `-e` flag for single-file tests when spawning Bun processes

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-11-24T18:37:11.466Z

Learnt from: CR
Repo: oven-sh/bun PR: 0
File: src/js/CLAUDE.md:0-0
Timestamp: 2025-11-24T18:37:11.466Z
Learning: Write JS builtins for Bun's Node.js compatibility and APIs, and run `bun bd` after changes

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-11-24T18:37:30.259Z

Learnt from: CR
Repo: oven-sh/bun PR: 0
File: test/CLAUDE.md:0-0
Timestamp: 2025-11-24T18:37:30.259Z
Learning: Applies to test/**/*.test.{ts,js,jsx,tsx,mjs,cjs} : Use `bun:test` with files that end in `*.test.{ts,js,jsx,tsx,mjs,cjs}`

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-10-19T02:44:46.354Z

Learnt from: theshadow27
Repo: oven-sh/bun PR: 23798
File: packages/bun-otel/context-propagation.test.ts:1-1
Timestamp: 2025-10-19T02:44:46.354Z
Learning: In the Bun repository, standalone packages under packages/ (e.g., bun-vscode, bun-inspector-protocol, bun-plugin-yaml, bun-plugin-svelte, bun-debug-adapter-protocol, bun-otel) co-locate their tests with package source code using *.test.ts files. This follows standard npm/monorepo patterns. The test/ directory hierarchy (test/js/bun/, test/cli/, test/js/node/) is reserved for testing Bun's core runtime APIs and built-in functionality, not standalone packages.

Applied to files:

• docs/bundler/executables.mdx

📚 Learning: 2025-11-24T18:35:50.422Z

Learnt from: CR
Repo: oven-sh/bun PR: 0
File: .cursor/rules/writing-tests.mdc:0-0
Timestamp: 2025-11-24T18:35:50.422Z
Learning: Applies to test/**/*.{js,ts,jsx,tsx} : Write tests as JavaScript and TypeScript files using Jest-style APIs (`test`, `describe`, `expect`) and import from `bun:test`

Applied to files:

• docs/bundler/executables.mdx

🔇 Additional comments (3)

docs/bundler/executables.mdx (3)

186-195: Clear and informative defaults documentation.

The restructured introduction effectively communicates the new default behavior. The Note about potential future changes to .env and bunfig.toml is a thoughtful addition for managing user expectations.

---

197-210: Well-structured enabling examples with clear flag naming.

The examples effectively demonstrate enabling tsconfig.json and package.json loading, including the combined usage case. The positive flag naming (--compile-autoload-*) aligns well with enabling disabled-by-default options.

---

227-244: Excellent JavaScript API documentation with clear default explanations.

The code example effectively documents all four autoload options with helpful inline comments that distinguish between disabled-by-default (tsconfig, package.json) and enabled-by-default (.env, bunfig.toml) options. The comments make it clear what each setting does relative to its default, which will help users understand which options they need to override.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}