use-bun

# Use Bun

Bun-first philosophy: prefer native APIs over external packages.

<when_to_use>

- Auditing existing projects for Bun migration opportunities
- Starting new TypeScript projects
- Evaluating whether to add a dependency
- Reviewing code that uses Node.js APIs
- Cleaning up package.json bloat

**Boundary**: This skill covers *when* to use Bun and *what* it replaces. For detailed Bun API patterns and implementation examples, see the `bun-dev` skill instead.

</when_to_use>

## CLI Commands

Use Bun directly instead of Node.js tooling:

| Instead of | Use |
| ---------- | --- |
| `node file.ts` or `ts-node file.ts` | `bun file.ts` |
| `jest` or `vitest` | `bun test` |
| `webpack` or `esbuild` (CLI) | `bun build` |
| `npm install` / `yarn` / `pnpm` | `bun install` |
| `npm run script` | `bun run script` |
| `npx package` | `bunx package` |
| `nodemon` | `bun --watch` |
| `node --env-file=.env` | `bun` (auto-loads .env) |

## Decision Framework

Before adding a dependency, follow this hierarchy:

```
Need functionality
│
├─► Does Bun have a built-in API?
│   └─► YES → Use it directly
│
├─► Can you wrap a Bun primitive?
│   └─► YES → Thin abstraction over Bun API
│
└─► External package (last resort)
    └─► Document why Bun couldn't do it
```

### Evaluation Checklist

1. Check Bun docs first: https://bun.sh/docs
2. Search for `Bun.` or `bun:` in docs
3. Test if Node.js API you're using has faster Bun equivalent
4. If adding package, verify Bun doesn't cover it natively

### When Packages Are Justified

- Framework-level abstractions (Hono, TanStack Router)
- Domain-specific logic (Zod schemas, date-fns)
- Protocol implementations Bun doesn't cover
- Battle-tested crypto beyond basic hashing

Document exceptions with a code comment:

```typescript
// Using date-fns: Bun has no date manipulation APIs
import { format, addDays } from 'date-fns';
```

## Quick Reference

Bun APIs organized by category. Check these before reaching for npm.

### Testing

| Bun API | Re