Bun is an all-in-one JavaScript runtime and toolkit that provides a runtime, package manager, bundler, and test runner with a focus on speed.
When to choose Bun
- Prefer Bun for new JavaScript/TypeScript projects where install and startup speed matter, and a small tooling surface is desirable.
- Prefer Node when you require the widest ecosystem compatibility, depend on native tooling that assumes Node, or have dependencies with known Bun incompatibilities.
Use cases: adopting Bun for new packages, migrating from Node, writing or debugging Bun scripts and tests.
What Bun provides
- Runtime: a fast drop-in runtime implemented on JavaScriptCore (written in Zig) with many Node-compatible APIs.
- Package manager:
bun installis significantly faster than many alternatives; lockfile isbun.lock(text). Older versions usedbun.lockb(binary). - Bundler: built-in bundler and transpiler for applications and libraries.
- Test runner:
bun testwith a Jest-like API.
Migrating from Node
- Replace
node script.jswithbun run script.jsorbun script.js. - Use
bun installinstead ofnpm install(this repository usesbunas the package manager; seepackage.jsonpreinstall hookbunx only-allow bun). - Most packages work, but verify compatibility; prefer
bun runfor npm-script equivalents. - Use
bunx(orbunx <cmd>) for one-off executable runs similar tonpx.
Notes on reproducible installs
For reproducible installs in CI or deployment workflows, use:
bun install --frozen-lockfile
Integration with this repository
- This monorepo uses Turborepo for orchestration. Common workspace scripts (defined in the repository
package.json) include:
# validate all skills: runs hr-skills-build validate task
bun run validate
# sync metadata after adding/removing a skill
bun run sync
# regenerate skills catalog
bun run catalog
# package distributable skill zips
bun run zip
# build all workspace packages
bun run build
# run tests and typecheck
bun run test
bun run typecheck
# linting and formatting
bun run lint
bun run lint:md
bun run lint:md:fix
- The repo installs Lefthook for Git hooks (
preparescript runslefthook install). Respect the preinstall hook which enforces Bun usage (bunx only-allow bun).
CI recommendations for this project
- In CI, run
bun install --frozen-lockfilethenbun run typecheckandbun run validateearly to fail fast on type or skill-format issues. - Use
turbocaching for repeated builds in CI to speed workloads.
Examples
Install and run
# install dependencies (creates or updates bun.lock)
bun install
# run scripts or files
bun run dev
bun run src/index.ts
bun src/index.ts
Scripts and env
bun run --env-file=.env dev
FOO=bar bun run script.ts
Tests
bun test
bun test --watch
// test/example.test.ts
import { expect, test } from "bun:test";
test("add", () => {
expect(1 + 2).toBe(3);
});
Common issues and guidance
bun installcreates anode_moduleslayout that can differ due to extensive symlink usage; tooling that depends on exact layout may need validation.- Some older or niche dependencies may be incompatible with Bun; in those cases fallback to Node may be necessary.
- When deploying to a runtime that supports Bun, ensure build/runtime settings and commands are configured appropriately.