rules_bun/docs/rules.md

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 stage hermetic bun, bunx, and node commands on PATH and 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 the staged Bun runtime tool bin and 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 the staged Bun runtime tool bin and 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 the staged Bun runtime tool bin and 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 the staged Bun runtime tool bin and 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. The staged Bun runtime tool bin and 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 <script>.	String	required
shell	Optional shell implementation for package scripts.	String	optional	""
silent	If true, suppresses Bun's command echo for package scripts.	Boolean	optional	False
smol	If true, enables Bun's lower-memory runtime mode.	Boolean	optional	False
working_dir	Working directory at runtime: Bazel runfiles workspace root or the directory containing package.json. The default package mode matches tools such as Vite that resolve config and assets relative to the package directory.	String	optional	"package"
workspaces	If true, runs the script in all workspace packages.	Boolean	optional	False

bun_test

load("@rules_bun//bun:defs.bzl", "bun_test")

bun_test(name, deps, srcs, data, bail, concurrent, coverage, coverage_reporters, env_files,
         install_mode, max_concurrency, no_env_file, node_modules, only, pass_with_no_tests, preload,
         randomize, reporter, rerun_each, retry, seed, smol, test_flags, timeout_ms, todo,
         update_snapshots)

Runs Bun tests as a Bazel test target.

Supports Bazel test filtering (--test_filter) and coverage integration.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Library dependencies required by test sources.	List of labels	optional	[]
srcs	Test source files passed to bun test.	List of labels	required
data	Additional runtime files needed by tests.	List of labels	optional	[]
bail	Optional failure count after which Bun exits the test run.	Integer	optional	0
concurrent	If true, treats all tests as concurrent tests.	Boolean	optional	False
coverage	If true, always enables Bun coverage output.	Boolean	optional	False
coverage_reporters	Repeated Bun coverage reporters such as text or lcov.	List of strings	optional	[]
env_files	Additional environment files loaded with --env-file.	List of labels	optional	[]
install_mode	Whether Bun may auto-install missing packages while testing. Hermetic tests require \"disable\", and other values are rejected.	String	optional	"disable"
inherit_host_path	If true, appends the host PATH after the staged Bun runtime tool bin and node_modules/.bin entries at runtime.	Boolean	optional	False
max_concurrency	Optional maximum number of concurrent tests.	Integer	optional	0
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
only	If true, runs only tests marked with test.only() or describe.only().	Boolean	optional	False
pass_with_no_tests	If true, exits successfully when no tests are found.	Boolean	optional	False
preload	Modules to preload with --preload before running tests.	List of labels	optional	[]
randomize	If true, runs tests in random order.	Boolean	optional	False
reporter	Test reporter format.	String	optional	"console"
rerun_each	Optional number of times to rerun each test file.	Integer	optional	0
retry	Optional default retry count for all tests.	Integer	optional	0
seed	Optional randomization seed.	Integer	optional	0
smol	If true, enables Bun's lower-memory runtime mode.	Boolean	optional	False
test_flags	Additional raw flags forwarded to bun test before the test source list.	List of strings	optional	[]
timeout_ms	Optional per-test timeout in milliseconds.	Integer	optional	0
todo	If true, includes tests marked with test.todo().	Boolean	optional	False
update_snapshots	If true, updates Bun snapshot files.	Boolean	optional	False

js_library

load("@rules_bun//bun:defs.bzl", "js_library")

js_library(name, deps, srcs, data, types)

Aggregates JavaScript sources and transitive Bun source dependencies.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other Bun source libraries to include transitively.	List of labels	optional	[]
srcs	JavaScript source files in this library.	List of labels	optional	[]
data	Optional runtime files propagated to dependents.	List of labels	optional	[]
types	Optional declaration files associated with this library.	List of labels	optional	[]

js_run_devserver

load("@rules_bun//bun:defs.bzl", "js_run_devserver")

js_run_devserver(name, deps, data, node_modules, package_dir_hint, package_json, tool, working_dir)

Runs an executable target from a staged JS workspace.

This is a Bun-backed compatibility adapter for rules_js-style devserver targets. It stages the same runtime workspace as the Bun rules, then executes the provided tool with any default arguments.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Library dependencies required by the dev server.	List of labels	optional	[]
data	Additional runtime files required by the dev server.	List of labels	optional	[]
node_modules	Optional label providing package files from a node_modules tree, typically produced by bun_install or npm_translate_lock, in runfiles.	Label	optional	None
package_dir_hint	Optional package-relative directory hint when package_json is not supplied.	String	optional	"."
package_json	Optional package.json used to resolve the package working directory.	Label	optional	None
tool	Executable target to launch as the dev server.	Label	required
inherit_host_path	If true, appends the host PATH after the staged Bun runtime tool bin and node_modules/.bin entries at runtime.	Boolean	optional	False
working_dir	Working directory at runtime: Bazel runfiles workspace root or the resolved package directory.	String	optional	"workspace"

ts_library

load("@rules_bun//bun:defs.bzl", "ts_library")

ts_library(name, deps, srcs, data, types)

Aggregates TypeScript sources and transitive Bun source dependencies.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other Bun source libraries to include transitively.	List of labels	optional	[]
srcs	TypeScript source files in this library.	List of labels	optional	[]
data	Optional runtime files propagated to dependents.	List of labels	optional	[]
types	Optional declaration files associated with this library.	List of labels	optional	[]

js_binary

load("@rules_bun//bun:defs.bzl", "js_binary")

js_binary(name, **kwargs)

PARAMETERS

Name	Description	Default Value
name	-	none
kwargs	-	none

js_test

load("@rules_bun//bun:defs.bzl", "js_test")

js_test(name, entry_point, srcs, **kwargs)

PARAMETERS

Name	Description	Default Value
name	-	none
entry_point	-	None
srcs	-	None
kwargs	-	none