rules_bun

bazel_dep(name = "rules_bun", version = "0.4.1")

common --registry=https://registry.fastverk.com/
common --registry=https://bcr.bazel.build/

bazel_dep(name = "rules_bun", version = "0.4.0")

bun = use_extension("@rules_bun//bun:extensions.bzl", "bun")
use_repo(bun, "bun")
register_toolchains("@bun//:bun_toolchain_def")

bun_deps = use_extension("@rules_bun//bun:extensions.bzl", "bun_deps")
bun_deps.install(
    name = "npm",
    package_json = "//:package.json",
    lock = "//:bun.lock",
)
use_repo(bun_deps, "npm")

bazel_dep(name = "aspect_rules_js", version = "3.1.2")

bun.toolchain(version = "1.3.14")

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

bun_test(
    name = "math_tests",
    srcs = glob(["*.test.ts"]),
    data = ["bunfig.toml"],
)

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

bun_run(
    name = "build",
    script = "scripts/build.ts",
)

# MODULE.bazel
bun_deps = use_extension("@rules_bun//bun:extensions.bzl", "bun_deps")
bun_deps.install(
    name = "npm",
    package_json = "//:package.json",
    lock = "//:bun.lock",
)
use_repo(bun_deps, "npm")

# BUILD.bazel
load("@rules_bun//bun:defs.bzl", "bun_bundle", "bun_test")

# bun test resolves deps from the staged closure (no bun install).
bun_test(
    name = "unit",
    srcs = glob(["*.test.ts"]),
    node_modules = "@npm//:node_modules",
)

# bun build runs directly via the toolchain Bun — no js_binary driver.
bun_bundle(
    name = "bundle",
    srcs = ["index.ts"],          # entry + local modules
    entry = "pkg/index.ts",       # workspace-relative entry path
    out = "app.mjs",
    node_modules = "@npm//:node_modules",
    external = ["pg-native"],
)

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

# The driver js_binary stages the bundle entry + its full linked
# node_modules closure into runfiles; bun_bundle runs it as a build
# action so that closure materializes, then shells out to the hermetic
# Bun toolchain. `data` must list the entry's :lib + every npm-link dep.
js_binary(
    name = "bundle_driver",
    entry_point = "@rules_bun//bun:bun-build-driver",
    data = [":lib", ":node_modules/pg", ":node_modules/source-map-support"],
)

bun_bundle(
    name = "bundle",
    driver = ":bundle_driver",
    entry = "packages/api/index.js",
    out = "api.mjs",
    format = "esm",
    # Keep native addons / runtime requires out of the bundle.
    external = ["pg-native", "@aws-sdk/client-ssm", "encoding", "source-map-support"],
)

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

js_binary(
    name = "cli_driver",
    entry_point = "@rules_bun//bun:bun-build-driver",
    data = [":lib", ":node_modules/pg"],
)

bun_compile(
    name = "cli",
    driver = ":cli_driver",
    entry = "apps/cli/index.js",
    out = "cli",
    # Omit `target` to compile for the host; set it to cross-compile,
    # e.g. "bun-linux-x64-modern" for a linux OCI image.
    target = "bun-linux-x64-modern",
    external = ["pg-native"],
)

bazel run //docs:update

Real usage, taken from the module’s examples/.

examples/BUILD.bazel

load("@examples_npm//:defs.bzl", "npm_link_all_packages")

package(default_visibility = ["//visibility:public"])

# Links the example pnpm workspace's node_modules at //examples, so Bun's
# resolver finds it by walking up from examples/bundle/ and examples/compile/.
npm_link_all_packages(name = "node_modules")

exports_files(["pnpm-lock.yaml"])

examples/bundle/BUILD.bazel

load("@aspect_rules_js//js:defs.bzl", "js_binary")
load("@rules_bun//bun:defs.bzl", "bun_bundle", "bun_test")

package(default_visibility = ["//visibility:public"])

# The driver js_binary stages the bundle entry (the .ts sources, transpiled by
# Bun directly) next to the linked node_modules closure in its runfiles, so when
# `bun_bundle` runs it the whole import graph resolves from the staged tree.
js_binary(
    name = "bundle_driver",
    data = [
        "greet.ts",
        "index.ts",
        "//examples:node_modules/is-number",
        "//examples:node_modules/source-map-support",
    ],
    entry_point = "@rules_bun//bun:bun-build-driver",
)

# Bundle examples/bundle/index.ts into one self-contained ESM file. is-number
# and ./greet are inlined; source-map-support stays external.
bun_bundle(
    name = "bundle",
    out = "app.mjs",
    driver = ":bundle_driver",
    entry = "examples/bundle/index.ts",
    external = ["source-map-support"],
    format = "esm",
    target = "node",
)

# Smoke test: the bundle exists, runs, inlines the dep + local module, and keeps
# the external un-inlined. Run from the `_main` runfiles root with the bundle
# staged as data.
bun_test(
    name = "bundle_test",
    srcs = ["bundle.test.ts"],
    data = [":bundle"],
)

examples/compile/BUILD.bazel

load("@aspect_rules_js//js:defs.bzl", "js_binary")
load("@rules_bun//bun:defs.bzl", "bun_compile")
load("@rules_shell//shell:sh_test.bzl", "sh_test")

package(default_visibility = ["//visibility:public"])

# Driver js_binary: stages the compile entry + its npm dep closure.
js_binary(
    name = "compile_driver",
    data = [
        "main.ts",
        "//examples:node_modules/is-number",
    ],
    entry_point = "@rules_bun//bun:bun-build-driver",
)

# Compile examples/compile/main.ts into a standalone native executable for the
# HOST platform (no `target`), so CI builds for its own OS/arch without cross
# toolchains. The output is itself runnable: `bazel run //examples/compile:app`.
bun_compile(
    name = "app",
    out = "app_host",
    driver = ":compile_driver",
    entry = "examples/compile/main.ts",
)

# Smoke test: the produced file is executable and runs.
sh_test(
    name = "app_test",
    srcs = ["run_test.sh"],
    args = ["$(rootpath :app)"],
    data = [":app"],
)

examples/install/BUILD.bazel

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

package(default_visibility = ["//visibility:public"])

# Pure-Bun flow: NO aspect_rules_js, NO pnpm-lock. The node_modules closure is
# staged by `bun_deps.install` (see //MODULE.bazel) from this directory's
# package.json + bun.lock via `bun install --frozen-lockfile`, and consumed
# below as `@install_npm//:node_modules`.

# Bundle examples/install/index.ts into one self-contained ESM file. `is-number`
# (from the staged node_modules) and `./greet` are inlined — Bun runs directly
# via the toolchain (no js_binary driver). This is the `node_modules`/native
# `bun_bundle` path.
bun_bundle(
    name = "bundle",
    srcs = [
        "greet.ts",
        "index.ts",
    ],
    out = "app.mjs",
    entry = "examples/install/index.ts",
    format = "esm",
    node_modules = "@install_npm//:node_modules",
    target = "node",
)

# Proof that `bun test` resolves a dep from the `bun_install` node_modules tree.
bun_test(
    name = "resolve_test",
    srcs = ["resolve.test.ts"],
    node_modules = "@install_npm//:node_modules",
)

# Smoke test that the produced bundle exists, runs, and inlined the dep.
bun_test(
    name = "bundle_test",
    srcs = ["bundle.test.ts"],
    data = [":bundle"],
)

exports_files([
    "package.json",
    "bun.lock",
])

from docs/defs.md

User-facing rules for rules_bun.

Four pieces:

• bun_test — runs bun test as a hermetic Bazel test action with explicit srcs + deps. Returns a BunTestInfo provider wrapping the test result file (for downstream consumers; the main consumer is the test framework, which only cares about exit codes).

• bun_run — sh_binary macro: bazel run //path:NAME invokes bun run <script> against the live workspace source. Intentionally non-hermetic (escapes the runfiles sandbox) for the dev loop. Counterpart to bun_test’s hermetic execution.

• bun_bundle — bundle a JS/TS entry point into one self-contained file with bun build. Returns BunBundleInfo.

• bun_compile — compile a JS/TS entry point into a standalone native executable with bun build --compile (Bun runtime + bundled JS). Returns BunBinaryInfo and is bazel run-nable.

All resolve the Bun binary via @rules_bun//bun:toolchain_type (set up by register_toolchains("@bun//:bun_toolchain_def") in your MODULE.bazel).

bun_bundle / bun_compile have two ways to provision node_modules:

• Bun-native (recommended; no aspect_rules_js, no pnpm-lock): pass a node_modules label (a @<name>//:node_modules from a bun_deps.install tag — see extensions.bzl) plus srcs (the entry

  • local modules). bun build runs directly via the toolchain Bun; a small shell driver stages the entry into a real tree and symlinks the closure so Bun resolves the import graph natively.

• Legacy aspect_rules_js: pass a driver js_binary whose entry point is @rules_bun//bun:bun-build-driver and whose data stages the build entry plus its full linked node_modules closure; aspect materializes that closure into the action runfiles.

driver and node_modules are mutually exclusive — set exactly one. bun_test likewise takes an optional node_modules for dep resolution.

bun_bundle

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

bun_bundle(name, srcs, out, driver, entry, external, format, node_modules, target)

Bundle a JS/TS entry into one file via the hermetic Bun toolchain. Either Bun-native (node_modules from bun_deps.install, no aspect_rules_js) or the legacy aspect driver js_binary path.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	Bun-native path. The entry file + any local modules it imports, declared as action inputs. Ignored on the legacy driver path (that stages sources via the js_binary’s data).	List of labels	optional	[]
out	The single bundled output file (conventionally *.mjs).	Label	required
driver	LEGACY aspect_rules_js path. A js_binary whose entry point is @rules_bun//bun:bun-build-driver and whose data stages the bundle entry + its full linked node_modules closure. Mutually exclusive with node_modules; set exactly one.	Label	optional	None
entry	Path of the entry point relative to the workspace root (e.g. packages/aion-cli/index.js). On the native path this is the execroot-relative path; on the legacy path it is relative to the driver’s _main runfiles root (same string in practice).	String	required
external	Module names to exclude from the bundle (passed as --external <name>, repeatable). Use for native addons and runtime requires that must stay external, e.g. pg-native, @aws-sdk/*, encoding, source-map-support.	List of strings	optional	[]
format	Bun --format. Defaults to esm so import.meta in deps stays valid under Node.	String	optional	"esm"
node_modules	Bun-native path. A node_modules closure (typically @<name>//:node_modules from a bun_deps.install tag). When set, bun build runs directly via the toolchain Bun (no js_binary driver, no aspect_rules_js): the closure is symlinked to the execroot root so Bun resolves the import graph by walking up from entry. Mutually exclusive with driver. Pair with srcs (the entry + local modules).	Label	optional	None
target	Bun --target: the intended execution environment for the bundle. Defaults to node.	String	optional	"node"

bun_compile

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

bun_compile(name, srcs, out, driver, entry, external, node_modules, target)

Compile a JS/TS entry into a standalone native executable (Bun runtime + bundled JS) via bun build --compile. Either Bun-native (node_modules) or the legacy aspect driver path.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	Bun-native path. The entry file + any local modules it imports, declared as action inputs. Ignored on the legacy driver path.	List of labels	optional	[]
out	The standalone executable output. On --target bun-windows-* give it a .exe suffix.	Label	required
driver	LEGACY aspect_rules_js path. A js_binary whose entry point is @rules_bun//bun:bun-build-driver and whose data stages the build entry + its full linked node_modules closure. Mutually exclusive with node_modules; set exactly one.	Label	optional	None
entry	Path of the entry point relative to the workspace root (e.g. apps/studio-cli/index.js).	String	required
external	Module names to keep external (--external <name>, repeatable). NOTE: native .node addons are NOT embedded by --compile — list them here and provide the .node files at runtime alongside the produced binary.	List of strings	optional	[]
node_modules	Bun-native path. A node_modules closure (typically @<name>//:node_modules from a bun_deps.install tag). When set, bun build --compile runs directly via the toolchain Bun (no js_binary driver, no aspect_rules_js). Mutually exclusive with driver. Pair with srcs.	Label	optional	None
target	Bun compile target triple. Empty (the default) compiles for the host platform. Cross-compile values: bun-linux-x64, bun-linux-x64-modern, bun-linux-x64-baseline, bun-linux-arm64, bun-darwin-x64, bun-darwin-arm64, bun-windows-x64, and the *-musl libc variants (e.g. bun-linux-x64-musl). A future enhancement could derive this from the Bazel --platforms via a transition; for v1 pass the string.	String	optional	""

bun_test

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

bun_test(name, srcs, data, node_modules)

Run bun test over the listed source files as a Bazel test target.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	Test files (typically *.test.ts, *.test.js). Each is passed to bun test explicitly so Bazel tracks them as inputs.	List of labels	required
data	Additional runtime inputs (fixtures, bunfig.toml, etc.).	List of labels	optional	[]
node_modules	Optional node_modules closure (typically @<name>//:node_modules from a bun_deps.install tag). Staged at the workspace runfiles root as node_modules/ so bun test resolves dependency imports without bun install. The Bun-native replacement for aspect_rules_js’s npm_link_all_packages.	Label	optional	None

BunBinaryInfo

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

BunBinaryInfo(binary, target)

A standalone native executable produced by bun build --compile.

FIELDS

Name	Description
binary	File: the standalone executable.
target	string: the Bun compile target triple (empty = host).

BunBundleInfo

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

BunBundleInfo(bundle, format)

A single-file bundle produced by bun build.

FIELDS

Name	Description
bundle	File: the bundled output.
format	string: the Bun output format (esm/cjs/iife).

BunTestInfo

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

BunTestInfo(result)

Result metadata for a bun test run.

FIELDS

Name	Description
result	File: the captured test output (stdout + stderr concatenated).

bun_run

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

bun_run(name, script, args, **kwargs)

Invoke bun run <script> against the live workspace source.

Escapes the runfiles sandbox via BUILD_WORKSPACE_DIRECTORY so Bun resolves modules + reads files from the user’s actual source tree. Intentionally NOT hermetic — that’s bun_test’s job.

PARAMETERS

Name	Description	Default Value
name	target name.	none
script	package-relative path to the Bun script entry point.	none
args	extra args passed to bun run after the script name.	None
kwargs	forwarded to the underlying sh_binary.	none

from docs/extensions.md

Module extensions for rules_bun.

Two extensions:

• bun — auto-fetches a prebuilt Bun binary for the host platform. Versions are sha256-pinned in private/known_versions.bzl. Consumers can override via the toolchain tag class.

  bun = use_extension("@rules_bun//bun:extensions.bzl", "bun")
  use_repo(bun, "bun")
  register_toolchains("@bun//:bun_toolchain_def")

  Pin a specific version:

  bun.toolchain(version = "1.3.14")

• bun_deps — Bun-native node_modules staging. Each install tag produces a repo @<name> whose :node_modules filegroup is a bun install --frozen-lockfile-ed tree. The pure-Bun replacement for aspect_rules_js’s npm_translate_lock + npm_link_all_packages (no pnpm-lock, no aspect_rules_js):

  bun_deps = use_extension("@rules_bun//bun:extensions.bzl", "bun_deps")
  bun_deps.install(
      name = "npm",
      package_json = "//:package.json",
      lock = "//:bun.lock",
  )
  use_repo(bun_deps, "npm")

  then bun_test(node_modules = "@npm//:node_modules", ...) and bun_bundle(node_modules = "@npm//:node_modules", ...).

The actual release fetching is delegated to @rules_github//github:repositories.bzl%github_binary_repository so that the URL-shape + sha-pinning logic stays consistent across all our rules_* repos.

bun

bun = use_extension("@rules_bun//bun:extensions.bzl", "bun")
bun.toolchain(version)

Sets up @bun as a Bazel-fetched prebuilt Bun binary.

TAG CLASSES

toolchain

Attributes

Name	Description	Type	Mandatory	Default
version	Override Bun version. Defaults to the value in known_versions.bzl.	String	optional	""

bun_deps

bun_deps = use_extension("@rules_bun//bun:extensions.bzl", "bun_deps")
bun_deps.install(name, bun_version, ignore_scripts, install_flags, lock, package_json,
                 trusted_dependencies)

Bun-native node_modules staging — @<name>//:node_modules from a bun install --frozen-lockfile. Replaces aspect_rules_js’s npm_translate_lock + npm_link_all_packages for pure-Bun repos.

TAG CLASSES

install

Stage a node_modules tree from a package.json + bun.lock.

Attributes

Name	Description	Type	Mandatory	Default
name	Name of the generated repo. Reference its node_modules as @<name>//:node_modules.	Name	required
bun_version	Bun version to fetch for the install. Empty = the toolchain extension’s default.	String	optional	""
ignore_scripts	Skip dependency lifecycle scripts (--ignore-scripts). Default True.	Boolean	optional	True
install_flags	Extra raw flags appended to bun install.	List of strings	optional	[]
lock	The bun.lock pinning the install (--frozen-lockfile).	Label	required
package_json	The package.json to install from.	Label	required
trusted_dependencies	Packages to --trust (run lifecycle scripts for) even when ignore_scripts is True.	List of strings	optional	[]

from docs/toolchains.md

Toolchain rule for rules_bun.

bun_toolchain wraps a single Bun binary as a Bazel toolchain. Consumers (the bun_test and bun_run rules) resolve Bun through @rules_bun//bun:toolchain_type, so users can register custom Bun binaries (locally-built fork, alternate version, baseline-CPU variant) via register_toolchains(...) without modifying rule attrs.

The module extension at @rules_bun//bun:extensions.bzl generates a default toolchain (@bun//:bun_toolchain_def) wrapping the prebuilt binary. Users register it from MODULE.bazel:

register_toolchains("@bun//:bun_toolchain_def")

bun_toolchain

load("@rules_bun//bun:toolchains.bzl", "bun_toolchain")

bun_toolchain(name, bun)

Declare a Bun binary as a Bazel toolchain.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
bun	Path to the Bun executable.	Label	required

BunToolchainInfo

load("@rules_bun//bun:toolchains.bzl", "BunToolchainInfo")

BunToolchainInfo(bun)

The Bun binary, resolved via a toolchain.

FIELDS

Name	Description
bun	File: the bun executable.