Skill: ivangdavila/bun (version 1.0.0)

--- name: Bun slug: bun version: 1.0.0 description: "Build with Bun runtime avoiding Node.js compatibility traps, bundler pitfalls, and package manager gotchas." metadata: {"clawdbot":{"emoji":"🥟","requires":{"bins":["bun"]},"os":["linux","darwin","win32"]}} --- ## When to Use User needs Bun expertise — fast JavaScript/TypeScript runtime, bundler, and package manager. Agent handles migration from Node, bundling for web/server, and troubleshooting compatibility issues. ## Quick Reference | Topic | File | |-------|------| | Node.js API differences | `node-compat.md` | | Bundler configuration | `bundler.md` | | Package management | `packages.md` | ## Runtime Compatibility Traps - `process.nextTick` timing differs from Node — race conditions appear that didn't exist before, use `queueMicrotask` for cross-runtime code - `__dirname` and `__filename` don't exist in ESM — use `import.meta.dir` and `import.meta.file`, forgetting causes ReferenceError - `fs.watch` misses events that Node catches — file watcher scripts silently miss changes, add polling fallback - `child_process.spawn` options subset — some stdio configurations silently ignored, test subprocess code explicitly - `cluster` module not supported — app crashes immediately if code uses cluster, must refactor to workers - `vm` module partial — sandboxed code may escape or behave differently, security implications ## Bundler Traps - `--target=browser` strips Node APIs silently — build succeeds, then runtime crashes on `fs`, `path`, etc. - `--splitting` requires `--format=esm` — error message doesn't mention this, just fails cryptically - Everything bundled by default — server code bundles node_modules, use `--external:package` for server deps - Tree-shaking assumes no side effects — code with side effects may be removed, add `"sideEffects": false` to package.json or lose code - CSS imports work differently than webpack — `url()` paths resolve wrong, test in actual browser - `--minify` mangles names aggressively — debugging production crashes is harder, use `--minify-syntax` for safer minification ## Package Manager Traps - `bun.lockb` is binary format — can't diff, can't merge, Git conflicts require delete and regenerate - Peer dependencies auto-installed unlike npm — version conflicts appear silently, different versions than npm would pick - `bun install` resolves differently than npm — "works on my machine" when teammate uses npm - Workspaces `link:` protocol behaves differently — imports from workspace packages may fail - `bun add` modifies `package.json` formatting — unwanted diff noise in commits - No `npm audit` equivalent — security vulnerabilities not surfaced automatically ## TypeScript Traps - Bun runs TypeScript directly without `tsc` — type errors don't stop execution, bugs ship to production - Type-only imports may be kept — bundle size larger than expected - `tsconfig.json` paths work differently — imports that worked in Node+tsc may fail - Decorators experimental — behavior may differ from tsc, especially with legacy decorators ## Testing Traps - `bun test` has different assertion API — tests written for Jest need adaptation - Mock timing differs — tests that pass in Jest may fail or flake - No native coverage like c8/nyc — need different tooling - Snapshot format incompatible with Jest — can't share snapshots between runners ## Hot Reload Traps - `bun --hot` doesn't reload native modules — changes require restart - State preserved across reloads — bugs from stale state hard to debug - WebSocket connections not re-established — clients appear connected but dead


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)