rules_bun/README.md

Bun rules for Bazel

rules_bun provides Bazel rules for running, testing, bundling, and developing JavaScript and TypeScript code with Bun.

Repository layout

This repository follows the standard Bazel ruleset layout:

/
  MODULE.bazel
  README.md
  bun/
    BUILD.bazel
    defs.bzl
    extensions.bzl
    repositories.bzl
    toolchain.bzl
  docs/
  examples/
  tests/

The public entrypoint for rule authors and users is @rules_bun//bun:defs.bzl.

Public API

rules_bun exports these primary rules:

• bun_binary
• bun_bundle
• bun_dev
• bun_script
• bun_test
• js_library
• ts_library

Reference documentation:

• Published docs site: https://eriyc.github.io/rules_bun/
• Generated rule reference: docs/rules.md
• Docs index: docs/index.md

To refresh generated rule docs:

bazel build //docs:rules_md && cp bazel-bin/docs/rules.md docs/rules.md

Bzlmod usage

Release announcements should provide a copy-pasteable module snippet in the standard ruleset form:

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

Then add the Bun repositories and register the toolchains in MODULE.bazel:

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

use_repo(
    bun_ext,
    "bun_linux_x64",
    "bun_linux_aarch64",
    "bun_darwin_x64",
    "bun_darwin_aarch64",
    "bun_windows_x64",
)

register_toolchains(
    "@rules_bun//bun:darwin_aarch64_toolchain",
    "@rules_bun//bun:darwin_x64_toolchain",
    "@rules_bun//bun:linux_aarch64_toolchain",
    "@rules_bun//bun:linux_x64_toolchain",
    "@rules_bun//bun:windows_x64_toolchain",
)

If you want Bazel-managed dependency installation, also add the module extension for bun_install:

bun_install_ext = use_extension("@rules_bun//bun:extensions.bzl", "bun_install")

bun_install_ext.install(
    name = "npm",
    package_json = "//:package.json",
    bun_lockfile = "//:bun.lock",
)

use_repo(bun_install_ext, "npm")

Legacy WORKSPACE usage

For non-Bzlmod consumers, the repository exposes a legacy setup macro in @rules_bun//bun:repositories.bzl:

load("@rules_bun//bun:repositories.bzl", "bun_register_toolchains")

bun_register_toolchains()

Loading rules in BUILD files

load(
    "@rules_bun//bun:defs.bzl",
    "bun_binary",
    "bun_bundle",
    "bun_dev",
    "bun_script",
    "bun_test",
    "js_library",
    "ts_library",
)

Common workflows

bun_script for package scripts

Use bun_script to expose a package.json script as a Bazel executable. This is the recommended way to run Vite-style dev, build, and preview scripts.

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

bun_script(
    name = "web_dev",
    script = "dev",
    package_json = "package.json",
    node_modules = "@npm//:node_modules",
    data = glob([
        "src/**",
        "static/**",
        "vite.config.*",
        "svelte.config.*",
        "tsconfig*.json",
    ]),
)

When node_modules is provided, executables from node_modules/.bin are added to PATH.

bun_dev for local development

Use bun_dev for long-running watch or hot-reload development targets.

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

bun_dev(
    name = "web_dev",
    entry_point = "src/main.ts",
    # Optional: run from the entry point directory so Bun auto-loads colocated .env files.
    # working_dir = "entry_point",
)

Supported development options include:

• watch_mode = "watch"
• watch_mode = "hot"
• restart_on = [...]
• working_dir = "workspace" | "entry_point"

Working directory behavior

bun_binary and bun_dev support working_dir:

• "workspace": run from the Bazel runfiles workspace root.
• "entry_point": run from the nearest ancestor of the entry point that contains .env or package.json.

Tests and examples

The repository keeps conformance and integration coverage in tests/ and usage samples in examples/.

Representative example docs:

• examples/basic/README.md
• examples/workspace/README.md

To validate the ruleset locally:

bazel test //tests/...