docs: --no-bundle flag scope, standalone HTML CSP and duplication, input sourcemaps, --pass-with-no-tests, overwrite behavior

[robobun]

Problem

• Several documented features have a hazard the docs do not mention. Each was checked against bun 1.4.3: bun build --no-bundle accepts --splitting, --external, --format, --banner, --footer, --sourcemap, --metafile, --bytecode and silently ignores them, and --no-bundle --watch builds once and never rebuilds (bun build --watch --no-bundle does not reload on file changes #14519); a standalone HTML build copies a CSP <meta> through while dropping nonce and inlining everything; an asset referenced N times is embedded N times (200 KB PNG x5 = 1.37 MB page); input //# sourceMappingURL maps are never composed; --pass-with-no-tests exists in --help but in no doc.
• Two statements are the opposite of the behavior in docs/bundler/esbuild.mdx: "Bun never allows overwriting" (bun build ./in.js --outfile=in.js replaces the source file without a prompt, esbuild refuses without --allow-overwrite), and --watch "No differences" (esbuild watches transform-only builds, bun build --no-bundle --watch does not rebuild).

Fix

• snippets/cli/build.mdx: say which options apply under --no-bundle, which ones Bun accepts but ignores, what --watch does there, and that --bytecode-depth needs --bytecode. The --watch entry points at it.
• bundler/standalone-html.mdx Limitations: per-reference inlining, and the CSP / dropped-nonce interaction. bundler/index.mdx sourcemap section and both esbuild.mdx sourcemap rows: Bun does not read input sourcemaps. esbuild.mdx --allow-overwrite and --watch rows: describe the real behavior.
• snippets/cli/test.mdx and test/discovery.mdx: document --pass-with-no-tests and the exit code without it. snippets/cli/install.mdx: --save-text-lockfile is the default since 1.2, --trust only acts on named packages.
• Docs only, active voice per the contributing guide, formatted with the repo prettier config.

Background

• docs/snippets/cli/*.mdx are the flag lists imported into the main pages (bundler/index.mdx imports snippets/cli/build.mdx), so a sentence there is what renders under "CLI Usage".
• Behaviors that are bugs rather than limitations stay out of this PR and have their own PRs: --no-bundle --watch rebuilding (bun build: install a file watcher for --no-bundle --watch #35633), --no-bundle --sourcemap (bun build --no-bundle: honor --sourcemap #38651), --no-bundle exiting 0 on an unresolvable entry (bun build --no-bundle: exit 1 when an entry point does not resolve #38752), multi-candidate srcset/imagesrcset (bundler(html): parse srcset into per-candidate imports #36012), --pass-with-no-tests with a missing path argument (bun test: honor --pass-with-no-tests when a single path argument does not exist #41924), input sourcemap composition itself (bundler: chain inline input sourcemaps through to output #30539, bundler: chain external input sourcemaps and thread chains through the dev server #32473), refusing to overwrite inputs (bundler: refuse to write an output file over one of the build's inputs #41612), and rewriting the CSP meta for standalone HTML (bundler: rewrite a Content-Security-Policy meta for what standalone HTML inlines #41954). Each of those changes a sentence added here; whichever lands second updates it. Relative-path --external not rebased, "1.0.0 || ^7" resolving to 1.0.0, and bun info pkg@unknown-tag printing latest are tracked separately without a docs change.

Notes

Commands used to check each statement (bun 1.4.3, linux x64):

• --no-bundle inert flags: bun build e.ts --no-bundle --banner='/*B*/' --footer='/*F*/' --metafile=meta.json --splitting --external=zzz --outdir=out exits 0, writes out/e.js with no banner/footer and no meta.json. --format=cjs and --format=iife still print ESM; --sourcemap=external|linked|inline write no map. --define, --env, --drop, --loader, --jsx-*, --minify, --tsconfig-override, --outdir/--outfile/--root/--entry-naming all take effect. --compile --no-bundle errors with "--compile does not support --no-bundle".
• --no-bundle --watch: bun build ./a.ts --no-bundle --watch --outdir out, then rewrite a.ts (in place and by rename): out/a.js keeps the first content and the log shows one "Transpiled file" line. The same steps without --no-bundle rebuild three times.
• --bytecode-depth=2 without --bytecode: plain .js output, exit 0.
• Standalone HTML: <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'nonce-abc'"> plus <script nonce="abc" type="module" src="./app.js"> builds to the same <meta> and a bare <script type="module">; grep -c nonce dist/index.html is 1 (the meta only).
• Duplication: five <img src="./logo.png"> of a 200 KB file give a 1,365,583 byte index.html with five data:image/png;base64, occurrences.
• Input sourcemaps: bundle an esbuild output that carries an inline map; Bun's entry.js.map has sources: ["../pre.js"], esbuild's has ["../orig.ts"].
• Overwrite: bun build ./in.js --outfile=in.js and --outdir=. both exit 0 and replace in.js; esbuild prints Refusing to overwrite input file "in.js" (use "--allow-overwrite" to allow this).
• --pass-with-no-tests: no test files -> exit 1 without, 0 with; -t zzz matching nothing -> exit 1 without, 0 with.
• bun install --trust with no package names: exit 0, package.json unchanged.

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{On-demand reviews are free for the next 12 days. After that, they cost $0.25 per reviewed file.}

Or wait 8 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 94b50b61-02c6-4d31-b71a-2b770fe886d5

📥 Commits

Reviewing files that changed from the base of the PR and between aecbe19 and ecffda4.

📒 Files selected for processing (7)

• docs/bundler/esbuild.mdx
• docs/bundler/index.mdx
• docs/bundler/standalone-html.mdx
• docs/snippets/cli/build.mdx
• docs/snippets/cli/install.mdx
• docs/snippets/cli/test.mdx
• docs/test/discovery.mdx

---

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

[robobun]

^{Updated 4:23 AM PT - Sep 8th, 2026}

✅ @robobun, your commit ecffda42b275f84af70eeead8b4745b3267be603 passed in Build #112846! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 41937

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

bun-41937 --bun

[robobun]

Status: docs only, no build needed. Every added sentence was checked against bun 1.4.3 with the commands listed under Notes in the PR body (release binary, linux x64). Behaviors that are bugs rather than limitations were deliberately kept out of the docs and are tracked in the PRs linked under Background.

[claude]

Findings marked 🟡 are optional suggestions and need no follow-up push.

[robobun]

Heads-up for the docs/bundler/standalone-html.mdx part: #41954 changes the CSP behavior this describes (the <meta http-equiv="Content-Security-Policy"> is rewritten with hashes of the inlined blocks and data: instead of copied through), and it adds the same "Repeated references" limitation. Whichever of the two lands second needs to reconcile those two bullets.

[claude]

LGTM — the follow-up commit addressed all three points from the earlier review: --watch is out of the --no-bundle "apply" list and its idle behavior is stated in both build.mdx and the esbuild --watch row; --sourcemap and --format are now in the inert list; and the flagged passive-voice sentences across index.mdx, esbuild.mdx, standalone-html.mdx, and build.mdx now name Bun as the actor.

Re-checked the updated --no-bundle flag partition against the transform-only path in build_command.rs / transpiler.rs — the applied vs. ignored split matches. Confirmed the --allow-overwrite row now describes the actual overwrite behavior rather than the previous inverted claim. The new --pass-with-no-tests and --trust wording match their CLI behavior. No code changes; docs-only.

Extended reasoning...

Overview

Docs-only PR touching seven .mdx files under docs/: bundler comparison table (esbuild.mdx), bundler sourcemap section (index.mdx), standalone HTML limitations, and three CLI snippet pages (build, install, test) plus test/discovery.mdx. It documents behavioral caveats — --no-bundle flag scope, input-sourcemap non-composition, output overwrite behavior, standalone HTML asset duplication and CSP interaction, --pass-with-no-tests, --save-text-lockfile default, and --trust requiring named packages.

Security risks

None. Pure documentation prose; no executable code, config, types, or build scripts touched.

Level of scrutiny

Low-to-moderate. The main risk in a docs PR is factual inaccuracy. The prior review round traced the --no-bundle code path (build_command.rs transform-only branch, transpiler.rs printer entry) and flagged three issues; the new commit fixed all of them. The remaining claims (overwrite behavior, --trust no-op on bare install, --pass-with-no-tests exit codes, CSP/nonce dropping, per-reference asset embedding) were verified by the PR author with reproducible commands in the description and are consistent with the source paths examined during the earlier review.

Other factors

No CODEOWNERS entry covers docs/. Bug hunt exited on dry_streak with zero findings this round. No outstanding third-party CHANGES_REQUESTED reviews. The change corrects a documented statement that was the opposite of runtime behavior (the old --allow-overwrite row), which is a net correctness improvement worth landing.