Skip to content

build: print standalone HTML to stdout when no --outdir or --outfile is given - #42006

Open
robobun wants to merge 4 commits into
robobun/ae672639/build-sourcemap-no-outdirfrom
robobun/e2b0edbc/standalone-html-stdout
Open

robobun wants to merge 4 commits into
robobun/ae672639/build-sourcemap-no-outdirfrom
robobun/e2b0edbc/standalone-html-stdout

Conversation

@robobun

@robobun robobun commented Sep 8, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #41879. Only the standalone HTML default changes.

Problem

  • bun build --compile --target=browser ./index.html with no --outdir or --outfile, run from the project directory, writes the compiled page over the source ./index.html and exits 0.
  • Cause: the standalone HTML branch of BuildCommand::exec defaulted outfile to basename(entry) (build_command.rs:306 on bun build: never derive an output directory from the entry point #41879). It keeps the .html extension, so it names the source.

Fix

  • Drop the default. The page goes to stdout, as for bun build ./index.ts.
  • Move bun build: never derive an output directory from the entry point #41879's check (a linked or external map needs --outdir or --outfile) below the standalone branch, so it covers this mode.
  • Bare --sourcemap means inline here too: Arguments.rs decides it from --outdir/--outfile only. Executables still get external.
  • Verified: test/bundler/standalone.test.ts (6 new cases, all fail on canary 367d939), one flipped row in test/bundler/cli.test.ts.

Background

Downsides

  • bun build --compile --target=browser ./src/index.html used to create ./index.html in the cwd. It now writes no file. Scripts that read that file need --outfile index.html.
  • --sourcemap=linked or =external on the flagless form is now an error. Before, it wrote two files into the cwd.
Notes

Repro. The report covers 1.3.14 and 1.4.2. Reproduced here on 1.4.3 and on canary 367d939:

d=$(mktemp -d); cd $d
printf '<!doctype html><html><body># my source<script src="./app.js"></script></body></html>\n' > index.html
echo 'console.log(1)' > app.js
bun build --compile --target=browser ./index.html; cat index.html   # the source is now the inlined page

With the entry in a subdirectory (./src/index.html) the same command dropped an index.html into the cwd instead. Two HTML entries already fail with Must use --outdir.

Behavior after this PR (on top of #41879):

  • bun build --compile --target=browser ./index.html: prints the page to stdout, writes nothing.
  • ... --sourcemap and ... --sourcemap=inline: stdout, map inlined in the <script>. This is the rule bun build: never derive an output directory from the entry point #41879 documents ("with no value: linked when writing to disk, inline when writing to stdout") and the rule Bun.build({ sourcemap: true }) uses (has_out_dir only, src/runtime/api/JSBundler.rs:679).
  • ... --sourcemap=linked / --sourcemap=external: error: cannot use a linked source map without --outdir or --outfile (use --sourcemap=inline to print it to stdout) (an external for the second), exit 1.
  • --outfile out/page.html [--sourcemap=...] and --outdir: unchanged from bun build: never derive an output directory from the entry point #41879 (a new standalone test covers --outfile + linked).
  • Executables: unchanged. The executable branch sets every kind other than none to external (build_command.rs, "secretly override it"), so it does not matter that bare --sourcemap now parses as inline when no --outfile is given. bun build --compile ./cli.ts --sourcemap still writes cli and cli.map, and the stack trace of the executable still maps to cli.ts. bun-build-compile-sourcemap.test.ts and compile-sourcemap-internal.test.ts pass.

An earlier revision of this PR left bare --sourcemap on the flagless form as an error (it resolved to linked because --compile was set at parse time). That contradicted the documented rule, so the second commit removes it.

Fail-before detail: on the build of #41879 alone, 4 of the first 5 standalone cases fail (the --outfile + linked case passes there, as intended). The bare --sourcemap case was added later. #41879's own test expected that command to write into the cwd.

The second commit was built and tested on a local merge of this branch into main 87466cf (no conflicts), together with the full standalone.test.ts and cli.test.ts.

The flagless form prints no build summary (Bundled N modules, the file table), same as for JS entries, because stdout carries the page. The output can be redirected to a file.

docs/bundler/standalone-html.mdx only showed --outdir=dist for the CLI. It gains an "Output location" section that states the stdout form.


no test proof · iteration 0 · platform-specific test(s) that do not run on this machine, deferring to CI, which covers all platforms: test/bundler/standalone.test.ts, test/bundler/cli.test.ts

…is given

`bun build --compile --target=browser ./index.html` with no output
location defaulted the outfile to the entry point's basename. Unlike
the executable default it keeps the .html extension, so from the
project directory it wrote the compiled page over the source file.

Drop the default. The single page goes to stdout like any other
single-output build. Move the linked/external source map check below
the point where the standalone branch clears the compile flag, so a
separate .map with nowhere to go is an error in this mode too.
@robobun

robobun commented Sep 8, 2026

Copy link
Copy Markdown
Collaborator Author

Status

Reproduced on 1.4.3, 1.4.2 and canary with the released binary:

d=$(mktemp -d); cd $d
printf '<!doctype html><html><body># my source<script src="./app.js"></script></body></html>\n' > index.html
echo 'console.log(1)' > app.js
sha1sum index.html
bun build --compile --target=browser ./index.html   # exit 0
sha1sum index.html                                   # hash changed: the source is now the compiled page

This PR targets the branch of #41879 and only changes the standalone HTML default on top of it. With both applied the command above prints the page to stdout and leaves index.html alone (test/bundler/standalone.test.ts, "CLI without --outdir or --outfile").

@robobun

robobun commented Sep 8, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 2:04 PM PT - Oct 16th, 2026

✅ @robobun, your commit 16cb03fb05a0097f84d9990a72c1be7d6f93b60f passed in Build #126808! 🎉


🧪   To try this PR locally:

bunx bun-pr 42006

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

bun-42006 --bun

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed this PR and didn't find any bugs. The check relocation and tests look correct, but the PR itself flags an open product decision (stdout default here vs. #41612's refuse-to-overwrite), so a maintainer should pick the direction before this lands.

What was reviewed:

  • Verified the relocated sourcemap check in build_command.rs still covers the original JS-stdout case (same !compile && outdir.is_empty() && outfile.is_empty() predicate) and now also fires for standalone HTML after compile is cleared; the added fetcher.is_none() gate only excludes the internal dependency-scanner path, which is not a user build.
  • Checked the new tests follow harness conventions — tempDir, concurrent pipe drain, stdout/stderr asserted before exitCode, source-file-untouched negative assertion, test.each over both linked/external, path-separator normalization for Windows.
  • Confirmed the flipped cli.test.ts case is a genuine behavior change the PR intends, not a weakened assertion.
Extended reasoning...

Overview

This PR changes the default output destination for bun build --compile --target=browser <entry>.html when neither --outdir nor --outfile is passed: instead of writing to basename(entry) in the cwd (which could clobber the source file), it now prints the single bundled page to stdout, matching regular bun build behavior for a lone JS entry. The Rust change in src/runtime/cli/build_command.rs is small: it drops the four-line implicit outfile = basename(entry) assignment and moves the "linked/external sourcemap needs an output location" check from the early output_to_stdout block down into the outdir.is_empty() && !compile block, so it fires after the standalone-HTML branch has cleared compile. Five new tests in standalone.test.ts cover stdout output, --sourcemap=inline, --sourcemap=linked|external rejection, and --outfile + linked map; one existing test in cli.test.ts is flipped from expecting cwd file writes to expecting the error. Docs gain an "Output location" section.

Security risks

None. This is CLI output-routing logic for the bundler; no auth, crypto, network, or untrusted-input parsing is touched. The change actually removes a data-loss footgun (silently overwriting a source file).

Level of scrutiny

Moderate for correctness, but the reason to defer is not correctness — it's the explicit "open decision" the PR description surfaces: whether the no-output-flag form should print to stdout (this PR) or fail with "refusing to overwrite input file" (#41612). That is a user-facing default-behavior choice between two competing PRs, and REVIEW.md's guidance on API/CLI surface changes plus the approval guidelines' "large-scale design decisions a human should weigh in on" both point to a maintainer call here. The PR is also stacked on #41879, so its base is not main.

Other factors

I traced the check relocation carefully: the original site gated on output_to_stdout, computed while compile was still true for standalone HTML, so it never covered that mode. The new site is inside outdir.is_empty() && !compile && fetcher.is_none() with an inner outfile.is_empty() — equivalent to the old predicate for regular JS builds, and now reached for standalone HTML because compile was cleared just above. The only added gate is fetcher.is_none(), which excludes the internal DependenciesScanner entrypoint (not a user bun build invocation) where sourcemap flags are irrelevant. The flipped cli.test.ts assertion is not a weakened test — it's the same intentional behavior change the new standalone.test.ts cases cover, and it now asserts the exact error string, exit 1, and that no files were written. Test hygiene is solid: tempDir, describe.concurrent, Promise.all pipe drain, stdout/stderr asserted before exitCode, negative "source untouched" and "no extra files" assertions, test.each for the linked/external variants, and Windows path normalization on Glob results.

…dout

Bare --sourcemap is linked when the build writes to disk and inline
when it prints to stdout. The parser treated --compile as writing to
disk, so the flagless standalone HTML form, which now prints to stdout,
resolved to linked and failed with 'cannot use a linked source map'.

Decide from --outdir and --outfile only. An executable is not affected:
it overrides any source map kind with external.
Comment thread src/runtime/cli/Arguments.rs Outdated
Comment on lines +2636 to +2638
// Same rule as `Bun.build({ sourcemap: true })`. `--compile` alone does not
// decide it: an executable gets `external` either way, and a standalone
// HTML page with no output location goes to stdout.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you need a paragraph-long comment to justify why the workaround is OK, the code is wrong — fix the code

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline finding, I also checked whether moving the linked/external source-map guard into the outdir.is_empty() && !compile && fetcher.is_none() block drops any case the old output_to_stdout check covered: the only path it no longer reaches is the dependency-scanner (fetcher) entry, which clears compile and never writes bundle output, and the executable --compile path still defaults outfile to the entry basename before this block, so it is unaffected.

Extended reasoning...

The change removes the outfile = basename(entry) default for standalone HTML in src/runtime/cli/build_command.rs, relocates the stdout source-map guard below the compile branch, and narrows writes_to_disk in src/runtime/cli/Arguments.rs to outdir/outfile only; no security-sensitive surface is touched. The one posted finding is a test-coverage nit for the executable --compile variant, which is otherwise shielded by the existing override to External in build_command.rs.

Comment thread src/runtime/cli/Arguments.rs Resolved
…n/e2b0edbc/standalone-html-stdout

The base moved the --sourcemap=inline hint of the linked/external error
onto a note line. Keep that text at the place this branch moves the
check to, and pin the two lines in the standalone HTML test.
The parser picks linked or inline for a bare --sourcemap from --outdir
and --outfile. Name the condition has_output_location so it reads as
what it checks, and drop the comment that explained the old name.

An executable relies on build_command.rs to turn either kind into
external. Add two CLI rows that build an executable with a bare
--sourcemap, with and without --outfile, and expect the .map next to
it.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review completed

Nothing new to post: everything this review found is already covered by existing comments on this pull request or didn't merit a separate one.

@robobun

robobun commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator Author

A note from #41879, the base of this branch. It has two new commits: 828064d takes the --outfile name as written (it is no longer a naming template), and cf2d33b merges main.

A trial merge of this branch onto cf2d33b has no textual conflict. One new row in test/bundler/cli.test.ts pins the default that this PR removes. The row with a standalone html build of [ext].html (describe --outfile takes the file name as written) builds src/[ext].html with --compile --target=browser and no --outfile, and expects [ext].html in the cwd. With this PR the page goes to stdout, so that row needs the same change as a standalone html build with --sourcemap and no --outdir writes to the cwd.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants