mcpField
B
bun

bun

github.com/dobroslavradosavljevicDevelopment345 installsUpdated 3d ago
Repository

About bun

bun is a skill for developers working with Bun’s runtime, package manager, test runner, bundler, and Node.js compatibility. It guides repository inspection, adoption, troubleshooting, migration, and focused verification.

Key features

  1. 01Inspect Bun setup and project configuration
  2. 02Guide runtime and package-manager workflows
  3. 03Cover tests, builds, and Node.js compatibility
  4. 04Recommend focused verification commands

Use cases

  1. 01Adopting Bun in an existing project
  2. 02Migrating installs and scripts to Bun
  3. 03Troubleshooting Bun version or lockfile changes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dobroslavradosavljevic/skills --skill bun

After installing, type/bunin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
node-compat-config.md
package-manager.md
runtime-apis.md
source-map.md
test-bundler-build.md
usage-guide.md

Details

From the project README

Bun

Use this skill when work touches the Bun runtime, package manager, test runner, bundler, bunfig.toml, Node compatibility, or migrating installs/scripts to Bun.

Snapshot: [email protected], @types/[email protected] / [email protected] (captured 2026-09-18, re-verified 2026-10-01 — still latest stable). Refresh from source-map.md if versions differ.

Workflow

  1. Inspect the local Bun surface:
    • bun --version / bun --revision (stable line is 1.4.x; prefer bun upgrade toward 1.4.2 when APIs matter).
    • Lockfile: bun.lock (text; lockfileVersion 2, or 3 with nested/version-scoped overrides) vs legacy bun.lockb.
    • package.json scripts, workspaces, catalogs, overrides, trustedDependencies, optional nativeDependencies / ignoreScripts / selfContained.
    • bunfig.toml (project + optional global), .npmrc, @types/bun, and TypeScript 6/7 "types": ["bun"].
    • Whether code uses Bun-native APIs (Bun.serve, Bun.Image, bun:sqlite, …) or Node APIs (node:*).
  2. For day-to-day how-to, progressive adoption, and troubleshooting, follow usage-guide.md first.
  3. Refresh docs when versions drift or the task touches Redis/SQL/HTTP2/HTTP3/FFI, lockfile/linker/globalStore, or a 1.3→1.4 upgrade. Start from source-map.md.
  4. Route deeper detail:
  5. Prefer Bun-native APIs and bun / bunx commands for greenfield Bun projects. Keep Node APIs when the codebase is already Node-shaped and works.
  6. Verify with the narrowest useful bun command (bun test, bun run, bun ci, or a focused Bun.serve smoke).

Core Judgment

  • Bun is runtime + package manager + test runner + bundler in one binary — not “just a faster Node”. 1.4 is a Rust rewrite of that binary with a larger stdlib (Image, WebView, markdown, cron, Terminal, XML/JSON5/JSONL).
  • Prefer bun / bunx over npm / npx / yarn / pnpm in commands for Bun projects.
  • Commit bun.lock. CI install: bun ci (frozen lockfile).
  • Dependency lifecycle scripts are blocked by default unless trusted — check bun pm untrusted after adding native packages (sharp, etc.).
  • New workspace lockfiles default to isolated linker (configVersion: 1); legacy lockfiles stay hoisted. Global virtual store is opt-in ([install] globalStore = true) and only applies to isolated.
  • Prefer Bun.serve for new HTTP services; know the default 10s idle timeout (SSE needs server.timeout(req, 0)). HTTP/2 (http2: true) and HTTP/3 (http3: true) are experimental.
  • Prefer bun:sqlite / Bun.SQL / Bun.redis / Bun.Image over heavier Node clients when writing Bun-first code.
  • bun --watch hard-restarts; bun --hot soft-reloads (globalThis persists) — good for servers.
  • Bun flags go before run: bun --watch run dev, not bun run dev --watch.
  • Bun.env is a launch snapshot; prefer process.env when values change at runtime.
  • bun build does not typecheck or emit .d.ts — run tsc when types matter.
  • bun:ffi is engine-native in 1.4 (cstring is a plain string). Prefer Node-API natives for production-critical FFI.
  • 1.3→1.4: Bun reports Node.js 26 (process.versions.modules 147); bunfig.toml strings must be quoted. Full list: node-compat-config.md.

Verification

Prefer repository-owned commands. For meaningful Bun work, cover the relevant subset:

  • bun --version and confirm lockfile / linker / globalStore expectations.
  • Focused bun test (path or -t pattern); --parallel / coverage / junit when CI cares.
  • bun ci or bun install --frozen-lockfile after lockfile edits.
  • Smoke bun run <entry> or Bun.serve with port: 0 + fetch.
  • After native deps: bun pm untrusted / trust as needed.
  • After bun build / --compile: run the output on the target platform.
  • Node-compat migrations: run the same suite under Bun and note partial modules.
  • After a 1.3→1.4 bump: native addons rebuilt for NODE_MODULE_VERSION 147; quoted bunfig.toml; no res.writeHeader().

Report which checks ran, which did not, and any Bun version assumptions that remain.

Comments

Markdown supported