Public API surface for Bun Bazel rules.
## Hermeticity And Determinism
- Hermetic rule surfaces: `bun_build`, `bun_bundle`, `bun_compile`, `bun_test`
- Runfiles-only executable surface: `bun_binary`
- Reproducible but non-hermetic repository surface: `bun_install`
- Local workflow helpers: `bun_script`, `bun_dev`, `js_run_devserver`
Strict defaults:
- `bun_build`, `bun_bundle`, `bun_compile`, and `bun_test` require `install_mode = "disable"`
- Runtime launchers do not inherit the host `PATH` unless `inherit_host_path = True`
## bun_binary
load("@rules_bun//bun:defs.bzl", "bun_binary")
bun_binary(name, deps, data, conditions, entry_point, env_files, install_mode, no_env_file,
node_modules, preload, run_flags, smol, working_dir)
Runs a JS/TS entry point with Bun as an executable target.
Use this rule for non-test scripts and CLIs that should run via `bazel run`.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| deps | Library dependencies required by the program. | List of labels | optional | `[]` |
| data | Additional runtime files required by the program. | List of labels | optional | `[]` |
| conditions | Custom package resolve conditions passed to Bun. | List of strings | optional | `[]` |
| entry_point | Path to the main JS/TS file to execute. | Label | required | |
| env_files | Additional environment files loaded with `--env-file`. | List of labels | optional | `[]` |
| install_mode | Whether Bun may auto-install missing packages at runtime. Non-`disable` values are runtime opt-ins and are not hermetic. | String | optional | `"disable"` |
| inherit_host_path | If true, appends the host PATH after staged `node_modules/.bin` entries at runtime. | Boolean | optional | `False` |
| no_env_file | If true, disables Bun's automatic `.env` loading. | Boolean | optional | `False` |
| node_modules | Optional label providing package files from a `node_modules` tree, typically produced by `bun_install`, in runfiles. | Label | optional | `None` |
| preload | Modules to preload with `--preload` before running the entry point. | List of labels | optional | `[]` |
| run_flags | Additional raw flags forwarded to `bun run` before the entry point. | List of strings | optional | `[]` |
| smol | If true, enables Bun's lower-memory runtime mode. | Boolean | optional | `False` |
| working_dir | Working directory at runtime: `workspace` root or nearest `entry_point` ancestor containing `.env`/`package.json`. | String | optional | `"workspace"` |
## bun_build
load("@rules_bun//bun:defs.bzl", "bun_build")
bun_build(name, deps, data, asset_naming, banner, build_flags, chunk_naming, conditions,
css_chunking, define, drop, emit_dce_annotations, entry_naming, entry_points, env, external,
feature, footer, format, install_mode, jsx_factory, jsx_fragment, jsx_import_source,
jsx_runtime, jsx_side_effects, keep_names, loader, metafile, metafile_md, minify,
minify_identifiers, minify_syntax, minify_whitespace, no_bundle, node_modules, packages,
production, public_path, react_fast_refresh, root, sourcemap, splitting, target)
Builds one or more entry points with `bun build`.
The rule emits a directory artifact so Bun can materialize multi-file output
graphs such as HTML, CSS, assets, and split chunks. Optional metafile outputs
may be requested with `metafile` and `metafile_md`.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| deps | Source/library dependencies that provide transitive inputs. | List of labels | optional | `[]` |
| data | Additional non-source files needed during building. | List of labels | optional | `[]` |
| asset_naming | Optional asset naming template. | String | optional | `""` |
| banner | Optional bundle banner text. | String | optional | `""` |
| build_flags | Additional raw flags forwarded to `bun build`. | List of strings | optional | `[]` |
| chunk_naming | Optional chunk naming template. | String | optional | `""` |
| conditions | Custom resolve conditions passed to Bun. | List of strings | optional | `[]` |
| css_chunking | If true, Bun chunks CSS across multiple entry points. | Boolean | optional | `False` |
| define | Repeated `--define` values such as `process.env.NODE_ENV:"production"`. | List of strings | optional | `[]` |
| drop | Repeated `--drop` values, for example `console`. | List of strings | optional | `[]` |
| emit_dce_annotations | If true, re-emits DCE annotations in the bundle. | Boolean | optional | `False` |
| entry_naming | Optional entry naming template. | String | optional | `""` |
| entry_points | Entry files to build, including JS/TS or HTML entry points. | List of labels | required | |
| env | Inline environment variable behavior passed to `--env`. | String | optional | `""` |
| external | Modules treated as externals (not bundled). | List of strings | optional | `[]` |
| feature | Repeated `--feature` values for dead-code elimination. | List of strings | optional | `[]` |
| footer | Optional bundle footer text. | String | optional | `""` |
| format | Output module format. | String | optional | `"esm"` |
| install_mode | Whether Bun may auto-install missing packages while executing the build. Hermetic builds require `\"disable\"`, and other values are rejected. | String | optional | `"disable"` |
| jsx_factory | Optional JSX factory override. | String | optional | `""` |
| jsx_fragment | Optional JSX fragment override. | String | optional | `""` |
| jsx_import_source | Optional JSX import source override. | String | optional | `""` |
| jsx_runtime | Optional JSX runtime override. | String | optional | `""` |
| jsx_side_effects | If true, treats JSX as having side effects. | Boolean | optional | `False` |
| keep_names | If true, preserves function and class names when minifying. | Boolean | optional | `False` |
| loader | Repeated `--loader` values such as `.svg:file`. | List of strings | optional | `[]` |
| metafile | If true, emits Bun's JSON metafile alongside the output directory. | Boolean | optional | `False` |
| metafile_md | If true, emits Bun's markdown metafile alongside the output directory. | Boolean | optional | `False` |
| minify | If true, enables all Bun minification passes. | Boolean | optional | `False` |
| minify_identifiers | If true, minifies identifiers only. | Boolean | optional | `False` |
| minify_syntax | If true, minifies syntax only. | Boolean | optional | `False` |
| minify_whitespace | If true, minifies whitespace only. | Boolean | optional | `False` |
| no_bundle | If true, transpiles without bundling. | Boolean | optional | `False` |
| node_modules | Optional label providing package files from a `node_modules` tree, typically produced by `bun_install`, for package resolution. | Label | optional | `None` |
| packages | Whether packages stay bundled or are treated as external. | String | optional | `"bundle"` |
| production | If true, sets `NODE_ENV=production` and enables Bun production mode. | Boolean | optional | `False` |
| public_path | Optional public path prefix for emitted imports. | String | optional | `""` |
| react_fast_refresh | If true, enables Bun's React fast refresh transform. | Boolean | optional | `False` |
| root | Optional root directory for multiple entry points. When omitted, `bun_build` derives one from the entry point parent directories to keep emitted files inside the declared output tree. | String | optional | `""` |
| sourcemap | Sourcemap emission mode. | String | optional | `"none"` |
| splitting | If true, enables code splitting. | Boolean | optional | `False` |
| target | Bun build target environment. | String | optional | `"browser"` |
## bun_bundle
load("@rules_bun//bun:defs.bzl", "bun_bundle")
bun_bundle(name, deps, data, build_flags, entry_points, external, format, install_mode, minify,
node_modules, sourcemap, target)
Bundles one or more JS/TS entry points using Bun build.
Each entry point produces one output JavaScript artifact.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| deps | Source/library dependencies that provide transitive inputs. | List of labels | optional | `[]` |
| data | Additional non-source files needed during bundling. | List of labels | optional | `[]` |
| build_flags | Additional raw flags forwarded to `bun build`. | List of strings | optional | `[]` |
| entry_points | Entry files to bundle. | List of labels | required | |
| external | Package names to treat as externals (not bundled). | List of strings | optional | `[]` |
| format | Output module format. | String | optional | `"esm"` |
| install_mode | Whether Bun may auto-install missing packages during bundling. Hermetic bundles require `\"disable\"`, and other values are rejected. | String | optional | `"disable"` |
| minify | If true, minifies bundle output. | Boolean | optional | `False` |
| node_modules | Optional label providing package files from a `node_modules` tree, typically produced by `bun_install`, for package resolution. | Label | optional | `None` |
| sourcemap | If true, emits source maps. | Boolean | optional | `False` |
| target | Bun build target environment. | String | optional | `"browser"` |
## bun_compile
load("@rules_bun//bun:defs.bzl", "bun_compile")
bun_compile(name, deps, data, asset_naming, banner, build_flags, bytecode, chunk_naming,
compile_autoload_bunfig, compile_autoload_dotenv, compile_autoload_package_json,
compile_autoload_tsconfig, compile_exec_argv, compile_executable, conditions,
css_chunking, define, drop, emit_dce_annotations, entry_naming, entry_point, env,
external, feature, footer, format, install_mode, jsx_factory, jsx_fragment,
jsx_import_source, jsx_runtime, jsx_side_effects, keep_names, loader, minify,
minify_identifiers, minify_syntax, minify_whitespace, no_bundle, node_modules, packages,
production, public_path, react_fast_refresh, root, sourcemap, splitting, target,
windows_copyright, windows_description, windows_hide_console, windows_icon,
windows_publisher, windows_title, windows_version)
Compiles a Bun program into a standalone executable with `bun build --compile`.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| deps | Source/library dependencies that provide transitive inputs. | List of labels | optional | `[]` |
| data | Additional non-source files needed during building. | List of labels | optional | `[]` |
| asset_naming | Optional asset naming template. | String | optional | `""` |
| banner | Optional bundle banner text. | String | optional | `""` |
| build_flags | Additional raw flags forwarded to `bun build`. | List of strings | optional | `[]` |
| bytecode | If true, enables Bun bytecode caching in the compiled executable. | Boolean | optional | `False` |
| chunk_naming | Optional chunk naming template. | String | optional | `""` |
| compile_autoload_bunfig | Whether the compiled executable auto-loads `bunfig.toml` at runtime. | Boolean | optional | `True` |
| compile_autoload_dotenv | Whether the compiled executable auto-loads `.env` files at runtime. | Boolean | optional | `True` |
| compile_autoload_package_json | Whether the compiled executable auto-loads `package.json` at runtime. | Boolean | optional | `False` |
| compile_autoload_tsconfig | Whether the compiled executable auto-loads `tsconfig.json` at runtime. | Boolean | optional | `False` |
| compile_exec_argv | Repeated `--compile-exec-argv` values prepended to the executable's `execArgv`. | List of strings | optional | `[]` |
| compile_executable | Optional Bun executable used for cross-compilation via `--compile-executable-path`. | Label | optional | `None` |
| conditions | Custom resolve conditions passed to Bun. | List of strings | optional | `[]` |
| css_chunking | If true, Bun chunks CSS across multiple entry points. | Boolean | optional | `False` |
| define | Repeated `--define` values such as `process.env.NODE_ENV:"production"`. | List of strings | optional | `[]` |
| drop | Repeated `--drop` values, for example `console`. | List of strings | optional | `[]` |
| emit_dce_annotations | If true, re-emits DCE annotations in the bundle. | Boolean | optional | `False` |
| entry_naming | Optional entry naming template. | String | optional | `""` |
| entry_point | Entry file to compile into an executable. | Label | required | |
| env | Inline environment variable behavior passed to `--env`. | String | optional | `""` |
| external | Modules treated as externals (not bundled). | List of strings | optional | `[]` |
| feature | Repeated `--feature` values for dead-code elimination. | List of strings | optional | `[]` |
| footer | Optional bundle footer text. | String | optional | `""` |
| format | Output module format. | String | optional | `"esm"` |
| install_mode | Whether Bun may auto-install missing packages while executing the build. Hermetic compile actions require `\"disable\"`, and other values are rejected. | String | optional | `"disable"` |
| jsx_factory | Optional JSX factory override. | String | optional | `""` |
| jsx_fragment | Optional JSX fragment override. | String | optional | `""` |
| jsx_import_source | Optional JSX import source override. | String | optional | `""` |
| jsx_runtime | Optional JSX runtime override. | String | optional | `""` |
| jsx_side_effects | If true, treats JSX as having side effects. | Boolean | optional | `False` |
| keep_names | If true, preserves function and class names when minifying. | Boolean | optional | `False` |
| loader | Repeated `--loader` values such as `.svg:file`. | List of strings | optional | `[]` |
| minify | If true, enables all Bun minification passes. | Boolean | optional | `False` |
| minify_identifiers | If true, minifies identifiers only. | Boolean | optional | `False` |
| minify_syntax | If true, minifies syntax only. | Boolean | optional | `False` |
| minify_whitespace | If true, minifies whitespace only. | Boolean | optional | `False` |
| no_bundle | If true, transpiles without bundling. | Boolean | optional | `False` |
| node_modules | Optional label providing package files from a `node_modules` tree, typically produced by `bun_install`, for package resolution. | Label | optional | `None` |
| packages | Whether packages stay bundled or are treated as external. | String | optional | `"bundle"` |
| production | If true, sets `NODE_ENV=production` and enables Bun production mode. | Boolean | optional | `False` |
| public_path | Optional public path prefix for emitted imports. | String | optional | `""` |
| react_fast_refresh | If true, enables Bun's React fast refresh transform. | Boolean | optional | `False` |
| root | Optional root directory for multiple entry points. | String | optional | `""` |
| sourcemap | Sourcemap emission mode. | String | optional | `"none"` |
| splitting | If true, enables code splitting. | Boolean | optional | `False` |
| target | Bun build target environment for the compiled executable. | String | optional | `"bun"` |
| windows_copyright | Optional Windows copyright metadata. | String | optional | `""` |
| windows_description | Optional Windows description metadata. | String | optional | `""` |
| windows_hide_console | When targeting Windows, hides the console window for GUI-style executables. | Boolean | optional | `False` |
| windows_icon | Optional Windows icon path passed directly to Bun. | String | optional | `""` |
| windows_publisher | Optional Windows publisher metadata. | String | optional | `""` |
| windows_title | Optional Windows executable title. | String | optional | `""` |
| windows_version | Optional Windows version metadata. | String | optional | `""` |
## bun_dev
load("@rules_bun//bun:defs.bzl", "bun_dev")
bun_dev(name, data, conditions, entry_point, env_files, install_mode, no_clear_screen, no_env_file,
node_modules, preload, restart_on, run_flags, smol, watch_mode, working_dir)
Runs a JS/TS entry point in Bun development watch mode.
This rule is intended for local dev loops (`bazel run`) and supports Bun
watch/HMR plus optional full restarts on selected file changes.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| data | Additional runtime files required by the dev process. | List of labels | optional | `[]` |
| conditions | Custom package resolve conditions passed to Bun. | List of strings | optional | `[]` |
| entry_point | Path to the main JS/TS file to execute in dev mode. | Label | required | |
| env_files | Additional environment files loaded with `--env-file`. | List of labels | optional | `[]` |
| install_mode | Whether Bun may auto-install missing packages in dev mode. This is a local workflow helper, not a hermetic execution surface. | String | optional | `"disable"` |
| inherit_host_path | If true, appends the host PATH after staged `node_modules/.bin` entries at runtime. | Boolean | optional | `False` |
| no_clear_screen | If true, disables terminal clearing on Bun reloads. | Boolean | optional | `False` |
| no_env_file | If true, disables Bun's automatic `.env` loading. | Boolean | optional | `False` |
| node_modules | Optional label providing package files from a `node_modules` tree, typically produced by `bun_install`, in runfiles. | Label | optional | `None` |
| preload | Modules to preload with `--preload` before running the entry point. | List of labels | optional | `[]` |
| restart_on | Files that trigger a full Bun process restart when they change. | List of labels | optional | `[]` |
| run_flags | Additional raw flags forwarded to `bun run` before the entry point. | List of strings | optional | `[]` |
| smol | If true, enables Bun's lower-memory runtime mode. | Boolean | optional | `False` |
| watch_mode | Bun live-reload mode: `watch` (default) or `hot`. | String | optional | `"watch"` |
| working_dir | Working directory at runtime: `workspace` root or nearest `entry_point` ancestor containing `.env`/`package.json`. | String | optional | `"workspace"` |
## bun_script
load("@rules_bun//bun:defs.bzl", "bun_script")
bun_script(name, data, conditions, env_files, execution_mode, filters, install_mode, no_env_file,
no_exit_on_error, node_modules, package_json, preload, run_flags, script, shell, silent,
smol, working_dir, workspaces)
Runs a named `package.json` script with Bun as an executable target.
Use this rule to expose existing package scripts such as `dev`, `build`, or
`check` via `bazel run` without adding wrapper shell scripts. This is a good fit
for Vite-style workflows, where scripts like `vite dev` or `vite build` are
declared in `package.json` and expect to run from the package directory with
`node_modules/.bin` available on `PATH`.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| data | Additional runtime files required by the script. | List of labels | optional | `[]` |
| conditions | Custom package resolve conditions passed to Bun. | List of strings | optional | `[]` |
| env_files | Additional environment files loaded with `--env-file`. | List of labels | optional | `[]` |
| execution_mode | How Bun should execute matching workspace scripts. | String | optional | `"single"` |
| filters | Workspace package filters passed via repeated `--filter` flags. | List of strings | optional | `[]` |
| install_mode | Whether Bun may auto-install missing packages while running the script. This is a local workflow helper, not a hermetic execution surface. | String | optional | `"disable"` |
| inherit_host_path | If true, appends the host PATH after staged `node_modules/.bin` entries at runtime. | Boolean | optional | `False` |
| no_env_file | If true, disables Bun's automatic `.env` loading. | Boolean | optional | `False` |
| no_exit_on_error | If true, Bun keeps running other workspace scripts when one fails. | Boolean | optional | `False` |
| node_modules | Optional label providing package files from a `node_modules` tree, typically produced by `bun_install`, in runfiles. Executables from `node_modules/.bin` are added to `PATH`, which is useful for scripts such as `vite`. | Label | optional | `None` |
| package_json | Label of the `package.json` file containing the named script. | Label | required | |
| preload | Modules to preload with `--preload` before running the script. | List of labels | optional | `[]` |
| run_flags | Additional raw flags forwarded to `bun run` before the script name. | List of strings | optional | `[]` |
| script | Name of the `package.json` script to execute via `bun run