bun-runtime

name	bun-runtime
description	This skill should be used when the user mentions "bun", "bunx", "npm install", "npm run", "node script.js", "npx", "yarn add", "pnpm", "package manager", "run tests", "bundle for distribution", or any Node.js/npm commands. Also use for JavaScript or TypeScript package management, testing, or script execution. Provides Bun-first runtime standards - all npm/node commands should use Bun equivalents.

JavaScript Runtime Standards

Runtime & Tooling Requirements

Bun Runtime (CRITICAL)

ALWAYS use Bun instead of Node.js or npm for all JavaScript and TypeScript work.

Package Management

# CORRECT - Use Bun
bun install
bun add <package>
bun remove <package>
bun update <package>

# INCORRECT - Do NOT use npm/yarn/pnpm
npm install
npm add <package>
yarn install
pnpm install

Script Execution

# CORRECT - Use Bun
bun run script-name
bun run dev
bun run build
bun run start

# INCORRECT - Do NOT use npm
npm run script-name

Prefer package.json Scripts (IMPORTANT)

If a script exists in package.json, always use it instead of running the tool directly.

# CORRECT - Use the project's configured scripts
bun run lint          # Instead of bunx eslint
bun run typecheck     # Instead of bunx tsc
bun run format        # Instead of bunx prettier
bun run test          # Instead of bunx jest

# INCORRECT - Running tools directly bypasses project configuration
bunx eslint src/
bunx tsc --noEmit
bunx prettier --write .

Why this matters:

• Scripts include project-specific flags and configuration
• Scripts may run multiple tools in sequence (e.g., lint + typecheck)
• Scripts ensure consistent behavior across team members
• Direct tool invocation may miss config files or use wrong options

Bun "run" shorthand: You can omit run when the script name doesn't conflict with a bun command:

bun lint              # Works - "lint" is not a bun command
bun typecheck         # Works - "typecheck" is not a bun command
bun format            # Works - "format" is not a bun command
bun test              # Runs bun's built-in test runner, NOT the "test" script
bun run test          # Use this to run the package.json "test" script
bun build             # Runs bun's bundler, NOT a "build" script
bun run build         # Use this to run the package.json "build" script

Common bun verbs to watch out for: test, run, install, add, remove, update, init, create, build

Executable Tools

# CORRECT - Use bunx
bunx <command>
bunx eslint
bunx prettier

# INCORRECT - Do NOT use npx
npx <command>

Direct Execution

# CORRECT - Use bun
bun script.js
bun index.js
bun --watch dev.js

# INCORRECT - Do NOT use node
node script.js

Testing

# CORRECT - Use bun test
bun test
bun test --watch
bun test --coverage

# INCORRECT - Do NOT use other test runners via npm
npm test
npm run jest

Fake Timers (MANDATORY for timer tests)

When testing code with setTimeout, setInterval, or Date, always use fake timers:

import { jest } from 'bun:test';

beforeEach(() => { jest.useFakeTimers(); });
afterEach(() => { jest.useRealTimers(); });

jest.advanceTimersByTime(1000);  // Advance fake time
jest.runAllTimers();             // Run all pending timers
jest.setSystemTime(new Date()); // Mock Date.now()

Never rely on real timers in tests - they cause slow, flaky, non-deterministic results.

Concurrency warning: Fake timers are global state. Tests using fake timers should not run in parallel. Use describe.sequential or ensure proper cleanup in afterEach.

See the testing-standards skill for comprehensive patterns and examples.

No Build Step Required

Unlike traditional JavaScript/TypeScript workflows, Bun runs source files directly:

• No transpilation: Bun executes TypeScript natively
• No compilation: JavaScript runs as-is
• No bundling for development: Only bundle (bun build) when packaging for distribution

This means the "build step" mentioned in generic development workflows does NOT apply to Bun projects. Skip any "run build" instructions when using Bun.

The bun build command is a bundler for creating distributable files - it's unusual to need this during normal development.

Mutation Testing

If the project has a mutate script in package.json, run bun run mutate after all tests pass to verify test quality.

Bun Installation

If Bun is not installed: curl -fsSL https://bun.sh/install | bash

REPL & Debugging

# CORRECT - Use bun
bun repl
bun --inspect script.js

# INCORRECT - Do NOT use node
node --inspect script.js

Why Bun?

• Performance: 3-4x faster than Node.js for most operations
• Built-in TypeScript: Native TS support without transpilation
• All-in-one: Runtime, package manager, bundler, and test runner
• npm Compatible: Works with existing npm packages and package.json
• Modern Defaults: ESM, top-level await, JSX support out of the box

Migration Notes

When working with existing projects:

• Bun respects package.json scripts and dependencies
• bun install reads package-lock.json and creates bun.lock
• All npm packages work with Bun (npm registry compatible)
• Replace node with bun in shebang lines: #!/usr/bin/env bun

Exception Cases

The ONLY time to use Node.js/npm is when:

• Explicitly debugging Node.js-specific compatibility issues
• Working with tools that have hard Node.js version dependencies
• User explicitly requests npm/node for a specific reason

In all other cases, default to Bun.