liminfoBun Runtime Reference
Free reference guide: Bun Runtime Reference
About Bun Runtime Reference
The Bun Runtime Reference is a searchable cheat sheet for Bun — the all-in-one JavaScript runtime, package manager, bundler, and test runner built on JavaScriptCore. The Runtime section covers the most-used built-in APIs: Bun.serve() for creating HTTP and WebSocket servers with a single fetch handler, Bun.file() for lazy file references with .text() / .json() / .arrayBuffer() readers, Bun.write() for writing strings, Blobs, or Response objects directly to disk, and Bun.spawn() for launching child processes and capturing their stdout as a standard Web API Response stream.
The CLI section documents the commands developers use every day: bun install for npm-compatible package installation (typically 10–25x faster than npm), bun run for executing scripts or TypeScript files directly without a separate transpilation step, bun create for scaffolding new projects from templates such as Elysia, React, or Next.js, and bun init for zero-config project bootstrapping. The Testing section covers bun test, which provides a Jest-compatible API including describe(), test(), expect(), and mock(), along with --watch mode for fast feedback loops during development.
The Bundler section explains bun build, which compiles TypeScript and JSX to browser-ready bundles with tree-shaking, and Bun.Transpiler for programmatic code transformation. The Config section covers bunfig.toml for setting the package registry, preload scripts, default test timeout, and channel/tag configuration. The Plugin section shows how Bun.plugin() hooks into the module resolution pipeline to support custom file formats like YAML or TOML at both build time and runtime. This reference is aimed at Node.js developers migrating to Bun, full-stack JavaScript engineers, and developers building Elysia or Hono APIs on Bun.
Key Features
- Bun.serve() HTTP/WebSocket server with fetch handler and port configuration
- Bun.file() lazy file reference with .text(), .json(), .arrayBuffer() readers
- Bun.password for bcrypt and argon2 hashing and verification
- Bun.CryptoHasher for SHA-256, MD5, and other hash algorithms with hex digest
- bun install, bun add, bun add -d for npm-compatible package management
- bun test with Jest-compatible expect() assertions and --watch mode
- bun build with --outdir and --target for browser/node/bun bundle targets
- bunfig.toml configuration for registry, preload scripts, and plugin setup
Frequently Asked Questions
What makes Bun different from Node.js?
Bun is built on JavaScriptCore (Safari's engine) instead of V8, and is implemented in Zig for low-level performance. It ships as a single binary that replaces Node.js, npm, a bundler (webpack/esbuild), and a test runner (Jest) simultaneously. Bun natively supports TypeScript and JSX without any configuration, and its file I/O (Bun.file, Bun.write) is significantly faster than Node's fs module due to direct system call usage.
Is Bun fully compatible with npm packages?
Bun's package manager is compatible with package.json and the npm registry. Most npm packages work without modification. Bun also implements Node.js built-in modules (fs, path, http, crypto, etc.) so the majority of Node.js code runs unmodified. Some packages that rely on native Node.js add-ons (.node files) or Node-specific internals may require compatibility shims.
How does bun test compare to Jest?
bun test implements the Jest API surface including describe(), test(), it(), expect(), beforeEach(), afterEach(), beforeAll(), afterAll(), and jest.mock(). Tests run significantly faster than Jest because Bun executes TypeScript natively without transpilation overhead and parallelizes test files. However, Jest plugins and custom reporters may not be compatible. bun test is sufficient for the vast majority of unit and integration test suites.
What is the purpose of Bun.plugin()?
Bun.plugin() lets you intercept module resolution and transform files before they are imported. You register an onLoad handler with a filter regex that matches file extensions like .yaml or .toml. Bun calls your handler with the file path, you return transformed source code, and Bun caches and executes it. Plugins work both at runtime (bun run) and at build time (bun build), making them more versatile than webpack loaders or Vite plugins which only run at build time.
How does Bun.file() differ from fs.readFile()?
Bun.file() creates a lazy BunFile reference — no I/O happens at creation time. You consume the file by calling .text(), .json(), .arrayBuffer(), or .stream() on the reference. This is semantically similar to the Fetch API's Response object, which lets you decide how to consume the body. In contrast, fs.readFile() immediately starts reading. BunFile also exposes .size and .type for metadata without reading the contents.
What is bunfig.toml used for?
bunfig.toml is Bun's configuration file, equivalent to .npmrc and parts of package.json scripts combined. The [install] section sets the npm registry URL and scoped package registries. The [run] section sets preload scripts that execute before every bun run invocation — useful for registering global mocks or environment setup. The [test] section configures test timeout, preload for tests, and coverage reporting.
Can Bun replace webpack or Vite for frontend bundling?
bun build is a production bundler that supports TypeScript, JSX, tree-shaking, code splitting, and targets browser, node, and bun runtimes. It is much faster than webpack. However, as of early 2025, bun build lacks a built-in development server with HMR (Hot Module Replacement). For frontend frameworks like React or Vue that rely on fast HMR during development, Vite is still the better choice. Bun is excellent for bundling server-side code and CLI tools.
How do I use Bun inside a monorepo with workspaces?
Bun supports npm workspaces via the workspaces field in the root package.json. Running bun install at the root installs all workspace packages and creates symlinks in node_modules. You can run scripts in a specific workspace with bun run --filter <workspace-name> <script>. Bun's workspace resolution is compatible with the npm workspaces spec, so existing monorepos using npm or yarn workspaces can switch by replacing the lockfile.