CodeVetter · Repo Unpack · System map
oven-sh/bun
One native executable with a Rust core, a C++ JSC binding layer, and a build-time-bundled TypeScript module layer. `src/runtime/bin_entry/mod.rs` is the C-ABI `main`; it initializes the crash handler, allocator, stdio, and stack limits, then hands off to `cli::Cli::start()` which decodes a `Tag` and dispatches to one of 34 subcommand bodies. Storage is not a database — it's the lockfile (`bun.lock` text / `bun.lockb` binary under `src/install/lockfile/`), the global package cache, and the standalone-executable graph appended to the binary itself. Builds go through `scripts/build.ts` → CMake/ninja + `cargo` per-crate rlibs; CI is a generated Buildkite pipeline (`.buildkite/ci.ts`) plus 25 GitHub Actions workflows. Deployment shape is a downloadable binary plus npm packages, Docker images (`dockerhub/`), and a VS Code extension (`packages/bun-vscode`).
- Process entry is `extern "C" fn main(argc, argv)` in `src/runtime/bin_entry/mod.rs`, which captures argv first (because musl static builds never pass argv to `.init_array` hooks), then initializes the crash handler, points ICU/libuv/BoringSSL at mimalloc, ignores SIGPIPE/SIGXFSZ, calls `output::stdio::init()`, `StackCheck::configure_thread()`, and finally `cli::Cli::start()` before `Global::exit(0)`.
- The allocator is selected at compile time: mimalloc is the `#[global_allocator]` normally, but under `bun_asan` the build swaps to `std::alloc::System` so the ASAN interceptor sees every allocation; the binary also strong-defines `__asan_default_options` and `__lsan_default_suppressions` from the binary crate (not an rlib) so the link actually picks them up.
- CLI dispatch is a flat `match tag { … }` over `bun_options_types::command_tag::Tag`, with every arm out-lined into its own `#[cold] #[inline(never)]` fn so `Cli::start` compiles to a jump table and cold subcommand bodies (`install`, `create`, bundler, test runner) don't share `.text` pages with the `bun run` startup chain.
- `Tag` enumerates 34 subcommands and each carries a single-byte `char()` code used in crash-report URLs, explicitly documented as needing to stay in sync with the external `oven-sh/bun.report` decoder.
- The Rust side is a Cargo workspace of ~200 member crates declared in the root `Cargo.toml`, tiered so lower crates (`bun_core`, `bun_sys`, `bun_paths`) never depend on `bun_jsc` or `bun_runtime`; `bun_runtime` is the graph root and every crate's rlib is an input to the final link.
- The JS engine boundary lives in two halves: Rust-side glue in `src/jsc/` (`VirtualMachine.rs` at 7,700 lines, `ModuleLoader.rs`, `event_loop.rs`) and 407 files of hand-written + generated C++ in `src/jsc/bindings/` (`BunObject.cpp`, `ZigGlobalObject`, `BunPlugin.h`, per-class `JS*` files).
- Built-in JS modules are authored as TypeScript under `src/js/{node,bun,internal,thirdparty,builtins}` and bundled into the binary by `src/codegen/bundle-modules.ts`; they are not ES modules — only string-literal `require()` and `$`-prefixed intrinsics are allowed.
- Code generation is build-integrated: `generate-classes.ts` turns `*.classes.ts` definitions into paired Rust + C++ bindings, alongside `generate-jssink.ts`, `generate-host-exports.ts`, `generate-js2native.ts`, `bundle-functions.ts` and `generate-node-errors.ts`.
- The build orchestrator is `scripts/build.ts`: it configures and runs ninja, supports profiles (`debug`, `release`, `release-asan`, `release-assertions`, `debug-local`), and implements build-then-exec arg routing where the first unrecognized arg starts the exec-args for the produced binary.
- External integrations are first-class runtime surface rather than libraries: Postgres/MySQL/SQLite (`src/sql/`), Valkey/Redis (`src/valkey/`), S3 with SigV4 signing (`src/s3_signing/`), and an npm registry client (`src/install/npm.rs`).
- Persistence for the package manager is the lockfile subsystem under `src/install/lockfile/`, which supports both the text `bun.lock` and legacy binary `bun.lockb` formats plus migration from other package managers (`src/install/migration/`, `src/install/pnpm.rs`).
- CI is a programmatically generated Buildkite pipeline: `.buildkite/ci.ts` (1,997 lines) emits build steps, baked machine-image steps, and sharded test steps whose parallelism is platform-dependent (20 shards on Linux, 8 on Windows, 2 on macOS) with per-platform timeouts.
- Twenty-five GitHub Actions workflows handle the non-Buildkite lanes — formatting, lint, Rust lints, source lints, bun-types tsc checks, FreeBSD smoke, release, docs deploy, and a family of automated vendor-bump workflows (`update-cares.yml`, `update-zstd.yml`, `update-libarchive.yml`, …).
- Sibling deliverables ship from `packages/`: the public `bun-types` TypeScript declarations (the only npm workspace in the root `package.json`), a VS Code extension, a debug-adapter/inspector protocol pair, a Lambda layer, and native plugin APIs for Rust and C.