Bun DocsBuild the mental model first
Understand Bun's four roles through familiar Node.js tooling
Last updated on
The short version
Bun is not merely a faster npm client. It combines work commonly handled by Node.js, npm/pnpm, Jest/Vitest, and tools such as esbuild into one bun executable.
| Familiar role | Bun entry point | Must you replace it now? |
|---|---|---|
| Node.js runtime | bun run app.ts | No; start with scripts or local development |
| npm / pnpm / Yarn | bun install | No; verify lockfiles and lifecycle scripts first |
| Jest / Vitest | bun test | No; migrate isolated unit tests first |
| esbuild / Rollup | bun build | No; keep framework build tools when required |
Two meanings of bun run
bun run server.ts # execute a file
bun run dev # execute the dev script in package.jsonIf a file and a script could share a name, use an explicit path and extension for source, such as bun run ./dev.ts, and bun run dev for the package.json script. --bun does not disambiguate the two; it forces locally installed CLIs that declare a Node.js shebang to run with Bun.
Place flags at the correct boundary:
bun --watch run dev # --watch belongs to Bun
bun run dev -- --port 4000 # --port belongs to the dev scriptTypeScript execution is not type checking
Bun strips TypeScript syntax and executes the result. Keep a real static check in CI:
{
"scripts": {
"typecheck": "tsc --noEmit",
"test": "bun test"
}
}Web APIs and Node.js APIs
Bun emphasizes standard Web APIs such as fetch, Request, Response, and WebSocket, while implementing broad Node.js compatibility. Native addons, loaders, framework adapters, and edge cases still require project-specific tests.
A low-risk adoption order
- Execute a standalone TypeScript script with
bun run. - Reproduce dependency installation with
bun installand reviewbun.lock. - Move isolated unit tests to
bun test. - Evaluate the production runtime or full build chain last.