[robobun]

Problem

• docs/bundler/esbuild.mdx says "No differences" for --outfile (line 47) and for external (line 124). Both differ from esbuild 0.28.1.
• --outfile: a build without --compile fails when it also emits an asset, a CSS file, or an external source map. bun build ignores --outfile when --outdir is set (src/runtime/cli/Arguments.rs:2997). esbuild writes that file next to the outfile, and reports Cannot use both "outfile" and "outdir".
• external: Bun compares a * pattern with the import text only (src/resolver/resolver.rs:1013). --external './lib/*' bundles ../lib/l imported from src/. esbuild keeps that import external.

Fix

• Replace the two cells with the differences. No other row changes.
• Each cell keeps the column width, so the diff is 2 lines and prettier --check passes.
• Verified: the rows in Notes on a debug build of main (7ca0042) and on esbuild 0.28.1. The --outfile rows ran again on 1.4.3-canary after the last edit.

Background

• The page is the migration guide from esbuild. "No differences" tells the reader that a flag needs no change.
• esbuild checks an external two times. The first check uses the import text. The second check uses the file path, for an entry that starts with ./, ../ or /. Bun's wildcard check has only the first step.
• The outfile row of the JavaScript API table (line 155) is not in this PR. docs: fix examples that do not run or type-check as written #41734 changes that row, and Add outfile to Bun.build #12629 asks for the key.

Notes

Files: index.ts imports ./lib/l. nested.ts imports ./src/a, and src/a.ts imports ../lib/l. svg.ts imports ./l.svg. css.ts imports ./s.css.

Command	bun (main 7ca0042)	esbuild 0.28.1 (--bundle)
svg.ts --outfile o/x.js (esbuild: --loader:.svg=file)	exit 1, cannot write multiple output files without an output directory	writes o/x.js and o/l-<hash>.svg
css.ts --outfile o/x.js	exit 1, Multiple files share the same output path	writes o/x.js and o/x.css
index.ts --outfile o/x.js --sourcemap=external	exit 1, cannot use an external source map without --outdir	writes o/x.js and o/x.js.map
index.ts --outfile x.js --outdir out	exit 0, writes out/index.js, no x.js	exit 1, Cannot use both "outfile" and "outdir"
nested.ts --external './lib/*'	lib/l.ts is bundled	import { l } from "./lib/l" stays
index.ts --external './lib/l.ts'	lib/l.ts is bundled	import { l } from "./lib/l.ts" stays
nested.ts --external './lib/l'	import { l } from "../lib/l" stays, as written	import { l } from "./lib/l", relative to the output directory

• Bun.build({ entrypoints: ["./nested.ts"], external: ["./lib/*"] }) gives the same result as the CLI row.
• The first revision of the --outfile cell began with "Writes one file." That sentence was false, and the second commit removes it. index.ts --outfile o/x.js --sourcemap=linked exits 0 and writes x.js and x.js.map. The bare --sourcemap does the same.
• On 1.4.3-canary those two files land next to the entry point, not in o/. That is Directories in --outfile are ignored with --sourcemap #19729 (open PR bun build: never derive an output directory from the entry point #41879). esbuild writes o/x.js and o/x.js.map. The cell makes no statement about a linked source map.
• With --compile, an asset is embedded and an external source map is written next to the executable (1.4.3-canary). So the first sentence of the cell says "Without --compile".
• The same three builds succeed with --outdir out in place of --outfile (1.4.3-canary).
• Line numbers are from main at 2596ac5. That commit is the one after 7ca0042, and it does not change the code that these rows exercise.
• Two open changes would each make one clause of the --outfile cell stale: bun build: never derive an output directory from the entry point #41879 (an external source map with --outfile) and the pending change for bun build: --outfile is ignored when used with --outdir, should error or infer output for single entry point #21406 (--outfile with --outdir).
• Related to bun build: --outfile is ignored when used with --outdir, should error or infer output for single entry point #21406 and Bun build doesn't respect relative paths correctly #25144 (the printed path of a file external).

---

no test proof · iteration 0 · docs-only change; test-proof not applicable

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 33 seconds.

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

• Source mode: Auto
• Repository: oven-sh/bun
• Branch: robobun/f8cc2bea/esbuild-page-outfile-external-rows
• File: .coderabbit.yaml
• Commit: 9dd1e11
• Layers: Repository YAML
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: ef76f22b-2da1-4645-9950-a7b6bd7ad9ea

Commits

Reviewing files that changed from the base of the PR and between 7ca0042 and 9dd1e11.

Files selected for processing: 1

• docs/bundler/esbuild.mdx

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[robobun]

^{Updated 1:27 PM PT - Nov 8th, 2026}

✅ @robobun, your commit 9dd1e11751997b357b23ee090595cdb906adbd13 passed in Build #138958! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 48092

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

bun-48092 --bun

[robobun]

Status: ready for review. Docs only, 2 lines in docs/bundler/esbuild.mdx.

How to reproduce the two differences (bun at main 7ca0042, esbuild 0.28.1):

mkdir -p lib src
echo 'export const l = 1;' > lib/l.ts
echo 'import { l } from "../lib/l"; export const a = l + 1;' > src/a.ts
echo 'import { a } from "./src/a"; console.log(a);' > nested.ts

# external: bun bundles lib/l.ts, esbuild keeps the import
bun build ./nested.ts --external './lib/*'
esbuild ./nested.ts --bundle --format=esm '--external:./lib/*'

# --outfile with --outdir: bun writes out/nested.js and no x.js, esbuild exits 1
bun build ./nested.ts --outfile x.js --outdir out
esbuild ./nested.ts --bundle --outfile=x.js --outdir=out

The outfile row of the JavaScript API table is not in this PR. #41734 changes that row, and #12629 asks for the key.

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[claude]

Code review found no issues

No high-confidence issues detected in this change.