276 lines
6.6 KiB
Markdown
276 lines
6.6 KiB
Markdown
# Bun rules for [Bazel](https://bazel.build)
|
|
|
|
`rules_bun` provides Bazel rules for running, testing, building, compiling,
|
|
bundling, and developing JavaScript and TypeScript code with Bun.
|
|
|
|
## Repository layout
|
|
|
|
This repository follows the standard Bazel ruleset layout:
|
|
|
|
```text
|
|
/
|
|
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_build`
|
|
- `bun_compile`
|
|
- `bun_bundle`
|
|
- `bun_dev`
|
|
- `bun_script`
|
|
- `bun_test`
|
|
- `js_binary`
|
|
- `js_test`
|
|
- `js_run_devserver`
|
|
- `js_library`
|
|
- `ts_library`
|
|
|
|
Reference documentation:
|
|
|
|
- Published docs site: https://eriyc.github.io/rules_bun/
|
|
- Generated build rule reference: [docs/rules.md](docs/rules.md)
|
|
- `bun_install` extension docs: [docs/bun_install.md](docs/bun_install.md)
|
|
- Docs index: [docs/index.md](docs/index.md)
|
|
|
|
To refresh generated rule docs:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```starlark
|
|
bazel_dep(name = "rules_bun", version = "0.4.0")
|
|
```
|
|
|
|
Then add the Bun repositories and register the toolchains in `MODULE.bazel`:
|
|
|
|
```starlark
|
|
bun_ext = use_extension("@rules_bun//bun:extensions.bzl", "bun")
|
|
|
|
use_repo(
|
|
bun_ext,
|
|
"bun_linux_x64",
|
|
"bun_linux_aarch64",
|
|
"bun_linux_x64_musl",
|
|
"bun_linux_aarch64_musl",
|
|
"bun_darwin_x64",
|
|
"bun_darwin_aarch64",
|
|
"bun_windows_x64",
|
|
"bun_windows_aarch64",
|
|
)
|
|
|
|
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` runs `bun install`, not `npm install`. In the example below,
|
|
`bun_deps` is just the Bazel repository name for the generated
|
|
`node_modules` tree. See [docs/bun_install.md](docs/bun_install.md) for the
|
|
full extension reference.
|
|
|
|
```starlark
|
|
bun_install_ext = use_extension("@rules_bun//bun:extensions.bzl", "bun_install")
|
|
|
|
bun_install_ext.install(
|
|
name = "bun_deps",
|
|
package_json = "//:package.json",
|
|
bun_lockfile = "//:bun.lock",
|
|
# Optional: include extra install-time files or allow Bun to reuse the
|
|
# host HOME/cache.
|
|
# install_inputs = ["//:.npmrc"],
|
|
# isolated_home = False,
|
|
)
|
|
|
|
use_repo(bun_install_ext, "bun_deps")
|
|
```
|
|
|
|
## `rules_js` compatibility layer
|
|
|
|
`rules_bun` now exposes a Bun-backed compatibility layer for the most common
|
|
`rules_js` entrypoints:
|
|
|
|
- `@rules_bun//js:defs.bzl` exports `js_binary`, `js_test`, `js_run_devserver`,
|
|
`js_library`, `ts_library`, and `JsInfo`.
|
|
- `@rules_bun//npm:extensions.bzl` exports `npm_translate_lock`, which creates a
|
|
Bun-installed external repo and generates `@<repo>//:defs.bzl` with
|
|
`npm_link_all_packages()`.
|
|
|
|
Example:
|
|
|
|
```starlark
|
|
load("@rules_bun//js:defs.bzl", "js_binary")
|
|
load("@npm//:defs.bzl", "npm_link_all_packages")
|
|
|
|
npm_link_all_packages()
|
|
|
|
js_binary(
|
|
name = "app",
|
|
entry_point = "src/main.ts",
|
|
node_modules = ":node_modules",
|
|
)
|
|
```
|
|
|
|
This is a compatibility subset, not a full reimplementation of `rules_js`.
|
|
Package aliases created by `npm_link_all_packages()` use sanitized target names
|
|
such as `npm__vite` or `npm__at_types_node`.
|
|
|
|
## Legacy WORKSPACE usage
|
|
|
|
For non-Bzlmod consumers, the repository exposes a legacy setup macro in
|
|
`@rules_bun//bun:repositories.bzl`:
|
|
|
|
```starlark
|
|
load("@rules_bun//bun:repositories.bzl", "bun_register_toolchains")
|
|
|
|
bun_register_toolchains()
|
|
```
|
|
|
|
## Loading rules in BUILD files
|
|
|
|
```starlark
|
|
load(
|
|
"@rules_bun//bun:defs.bzl",
|
|
"bun_binary",
|
|
"bun_build",
|
|
"bun_compile",
|
|
"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.
|
|
|
|
```starlark
|
|
load("@rules_bun//bun:defs.bzl", "bun_script")
|
|
|
|
bun_script(
|
|
name = "web_dev",
|
|
script = "dev",
|
|
package_json = "package.json",
|
|
node_modules = "@bun_deps//: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`. This label typically comes from `bun_install`, which still produces a
|
|
standard `node_modules/` directory.
|
|
|
|
### `bun_build` and `bun_compile`
|
|
|
|
Use `bun_build` for general-purpose `bun build` output directories and
|
|
`bun_compile` for standalone executables built with `bun build --compile`.
|
|
|
|
```starlark
|
|
load("@rules_bun//bun:defs.bzl", "bun_build", "bun_compile")
|
|
|
|
bun_build(
|
|
name = "site",
|
|
entry_points = ["src/index.html"],
|
|
data = glob(["src/**"]),
|
|
splitting = True,
|
|
metafile = True,
|
|
)
|
|
|
|
bun_compile(
|
|
name = "cli",
|
|
entry_point = "src/cli.ts",
|
|
)
|
|
```
|
|
|
|
`bun_build` exposes a directory output so Bun can emit HTML, CSS, assets, and
|
|
split chunks. `bun_compile` produces a single executable artifact and supports
|
|
explicit cross-compilation via `compile_executable`.
|
|
|
|
### `bun_dev` for local development
|
|
|
|
Use `bun_dev` for long-running watch or hot-reload development targets.
|
|
|
|
```starlark
|
|
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/](tests/) and
|
|
usage samples in [examples/](examples/).
|
|
|
|
Representative example docs:
|
|
|
|
- [examples/basic/README.md](examples/basic/README.md)
|
|
- [examples/workspace/README.md](examples/workspace/README.md)
|
|
- [examples/vite_monorepo/README.md](examples/vite_monorepo/README.md)
|
|
|
|
To validate the ruleset locally:
|
|
|
|
```bash
|
|
bazel test //tests/...
|
|
```
|