Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robobun wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
31115ed
docs: state which flags apply under --no-bundle, standalone HTML CSP …
robobun Sep 8, 2026
ecffda4
docs: --watch does not rebuild under --no-bundle, list --format/--sou…
robobun Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/bundler/esbuild.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,11 @@ In Bun's CLI, boolean flags like `--minify` take no argument. Flags that take on
| `--packages` | `--packages` | No differences |
| `--platform` | `--target` | Renamed to `--target` for consistency with tsconfig. Does not support `neutral`. |
| `--serve` | n/a | Not applicable |
| `--sourcemap` | `--sourcemap` | Supports `linked` (the default when no value is given), `external`, `inline`, and `none`. Does not support esbuild's `both`. |
| `--sourcemap` | `--sourcemap` | Supports `linked` (the default when no value is given), `external`, `inline`, and `none`. Does not support esbuild's `both`. Bun does not read input sourcemaps (a `//# sourceMappingURL` comment in a source file), so it does not compose them into the output map the way esbuild does. |
| `--splitting` | `--splitting` | No differences |
| `--target` | n/a | Not supported. Bun's bundler performs no syntactic down-leveling. |
| `--watch` | `--watch` | No differences |
| `--allow-overwrite` | n/a | Bun never allows overwriting |
| `--watch` | `--watch` | No differences for bundles. With `--no-bundle`, Bun runs the first build and then keeps the process alive without rebuilding on change, whereas esbuild also watches transform-only builds. |
| `--allow-overwrite` | n/a | No flag. `bun build` always writes its output files and replaces whatever exists at those paths without a prompt. This includes an output path that is also one of the build's inputs, so keep `--outdir`/`--outfile` away from your source files. |
| `--analyze` | n/a | Not supported |
| `--asset-names` | `--asset-naming` | Renamed for consistency with naming in JS API |
| `--banner` | `--banner` | Only applies to js bundles |
Expand Down Expand Up @@ -162,7 +162,7 @@ In Bun's CLI, boolean flags like `--minify` take no argument. Flags that take on
| `reserveProps` | n/a | Not supported |
| `resolveExtensions` | n/a | Not supported |
| `sourceRoot` | n/a | Not supported |
| `sourcemap` | `sourcemap` | Supports `"none"`, `"linked"`, `"inline"`, and `"external"` |
| `sourcemap` | `sourcemap` | Supports `"none"`, `"linked"`, `"inline"`, and `"external"`. Bun does not read input sourcemaps in source files or compose them into the output map. |
| `sourcesContent` | n/a | Not supported |
| `splitting` | `splitting` | No differences |
| `stdin` | n/a | Not supported |
Expand Down
2 changes: 2 additions & 0 deletions docs/bundler/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -763,6 +763,8 @@ Specifies the type of sourcemap to generate.

The associated `*.js.map` sourcemap is a JSON file containing an equivalent `debugId` property.

The generated sourcemap maps to the files the bundler read. When an input file is itself generated code with its own `//# sourceMappingURL` comment (inline, or a `.map` file next to it), Bun does not read that input sourcemap. The output map then points at the generated file, not at its original source.

### minify

Whether to enable minification. Default `false`.
Expand Down
2 changes: 2 additions & 0 deletions docs/bundler/standalone-html.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,4 +311,6 @@ Bun replaces references to `process.env.API_URL` in your JavaScript with the lit

- **Code splitting** is not supported — `--splitting` cannot be used with `--compile --target=browser`
- **Large assets** increase file size since they're base64-encoded (33% overhead vs the raw binary)
- **Repeated references** to one asset each embed their own copy. A `data:` URI cannot be shared, so Bun stores an image used by two `<img>` tags, a CSS `url()` and a JS import four times. When size matters, reference a large asset from one place (one CSS class, or one JS import that the rest of the code reuses)
- **External URLs** (CDN links, absolute URLs) stay as-is: Bun inlines only relative paths
- **Content Security Policy**: the output relies on inline `<script>` and `<style>` elements and `data:` URLs. Bun copies a `<meta http-equiv="Content-Security-Policy">` tag from the source HTML through unchanged, so a policy that lacks `'unsafe-inline'` (or matching hashes) and `data:` sources blocks the inlined code and assets. Bun generates the inline `<script>` and `<style>` elements fresh and drops `nonce` and every other attribute of the original `<script>` and `<link>` tags
12 changes: 9 additions & 3 deletions docs/snippets/cli/build.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ bun build <entry points>
</ParamField>

<ParamField path="--bytecode-depth" type="number">
How many levels of nested functions to compile to bytecode ahead of time (a non-negative integer). Defaults to all
How many levels of nested functions to compile to bytecode ahead of time (a non-negative integer). Defaults to all.
Only has an effect together with <code>--bytecode</code>
</ParamField>

<ParamField path="--target" type="string" default="browser">
Expand Down Expand Up @@ -122,7 +123,12 @@ bun build <entry points>
</ParamField>

<ParamField path="--no-bundle" type="boolean">
Transpile only — do not bundle
Transpile only — do not bundle. Bun transpiles each entry point on its own and leaves its imports as written.
Transpiler options (`--define`, `--env`, `--drop`, `--loader`, the `--jsx-*` flags, `--minify`, `--tsconfig-override`)
and output options (`--outdir`, `--outfile`, `--root`, `--entry-naming`) apply. Bun accepts options that describe a
bundle (`--splitting`, `--external`, `--packages`, `--format`, `--banner`, `--footer`, `--sourcemap`, `--metafile`,
`--metafile-md`, `--bytecode`) but ignores them in this mode. `--watch` runs the first build and then keeps the
process alive without rebuilding. Bun rejects `--compile` together with `--no-bundle`
</ParamField>

<ParamField path="--css-chunking" type="boolean">
Expand Down Expand Up @@ -163,7 +169,7 @@ bun build <entry points>
### Development Features

<ParamField path="--watch" type="boolean">
Rebuild automatically when files change
Rebuild automatically when files change. Applies to bundles; see `--no-bundle` for the transpile-only case
</ParamField>

<ParamField path="--no-clear-screen" type="boolean">
Expand Down
7 changes: 5 additions & 2 deletions docs/snippets/cli/install.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,8 @@ bun install <name>@<version>
</ParamField>

<ParamField path="--save-text-lockfile" type="boolean">
Save a text-based lockfile
Save a text-based lockfile (<code>bun.lock</code>). This is the default since Bun v1.2, so the flag only matters when
migrating an existing binary <code>bun.lockb</code>
</ParamField>

<ParamField path="--lockfile-only" type="boolean">
Expand Down Expand Up @@ -148,7 +149,9 @@ bun install <name>@<version>
</ParamField>

<ParamField path="--trust" type="boolean">
Add to trustedDependencies in the project's package.json and install the package(s)
Add the packages named on the command line to <code>trustedDependencies</code> in the project's package.json and
install them. Has no effect on a bare <code>bun install</code> with no package names; use <code>bun pm trust</code>
for packages that are already installed
</ParamField>

### Concurrency & Performance
Expand Down
5 changes: 5 additions & 0 deletions docs/snippets/cli/test.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,11 @@ bun test <patterns>
Run only tests with a name that matches the given regex. Alias: <code>-t</code>
</ParamField>

<ParamField path="--pass-with-no-tests" type="boolean">
Exit with code 0 when <code>bun test</code> finds no test files or <code>--test-name-pattern</code> matches no test.
Without this flag both cases exit with code 1
</ParamField>

### Reporting

<ParamField path="--reporter" type="string">
Expand Down
8 changes: 8 additions & 0 deletions docs/test/discovery.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,14 @@ describe("Math", () => {

For this test, `bun test` matches the pattern against the string "Math operations should add correctly".

### When Nothing Matches

When `bun test` finds no test file, or a filter or `--test-name-pattern` matches nothing, it reports that and exits with code 1. Pass `--pass-with-no-tests` to exit with code 0 instead, for example in a shared CI step that runs before a package has any tests:

```bash terminal icon="terminal"
bun test --pass-with-no-tests
```

### Changing the Root Directory

By default, Bun looks for test files starting from the current working directory. Change this with the `root` option in `bunfig.toml`:
Expand Down