Bun

Build with Bun runtime avoiding Node.js compatibility traps, bundler pitfalls, and package manager gotchas.

Security Scan

The skill is an instruction-only Bun migration/build guide that only requires the bun binary and its content aligns with that purpose.

Purpose & Capability

Name/description ask for Bun expertise and the skill only requires the 'bun' binary and provides migration/build guidance — these requirements match the stated purpose.

Instruction Scope

SKILL.md and the included docs contain actionable commands (bun build, bun install, rm -rf node_modules, delete lockfiles, etc.) and checklists directly relevant to migrating/building with Bun. These commands can modify repositories and on-disk files (e.g., deleting lockfiles or node_modules), so they are in-scope but potentially destructive if run without review.

Install Mechanism

No install spec or code files — instruction-only skill. No downloads or archive extraction are requested.

Credentials

The skill requests no environment variables, credentials, or config paths. All references are to project files and Bun behavior, which is proportionate to the stated purpose.

Persistence & Privilege

always:false and no requests to modify other skills or global agent config. The skill does include instructions that, if executed, change local project files, but it doesn't request elevated or persistent platform privileges.

Assessment

This skill is an instruction-only Bun expert guide and appears coherent with that purpose. It assumes you have the bun binary available and includes commands that will modify project files (e.g., deleting lockfiles, removing node_modules, running bun install, building bundles). Before letting an agent execute these instructions: ensure you have backups or commits, run commands in a disposable environment or branch, confirm the agent only runs commands you expressly approve, and verify team CI/workflow compatibility (mixed npm/yarn teams may be affected). No credentials are requested, and there are no install downloads, but be cautious because the advice includes destructive filesystem operations if executed automatically.

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