bun-runtime · git:20251007.8d64d27 · 2025-10-07 · sha256 e7e955673cd3d61c

bun-runtime git:20251007.8d64d27A

Immutable. This exact content never changes and is served at /api/v1/blob/e7e955673cd3d61c.

---
description: Bun runtime patterns and best practices
alwaysApply: true
---

# Bun Runtime Rules

## Process Spawning (CRITICAL)

### Always Use Process Manager

```typescript
// ❌ WRONG - Creates zombie processes
import { spawn } from 'bun';
const proc = Bun.spawn(['command']);

// ❌ WRONG - Old Node.js pattern
import { spawn } from 'child_process';

// ✅ CORRECT - Tracked and cleaned up
import processManager from './tests/utils/process-cleanup';
const proc = processManager.spawn(['command'], options);
```

See [Process Management Rules](mdc:.cursor/rules/process-management.mdc) for details.

## File Operations

**Use Bun APIs, not Node.js fs:**

```typescript
// ✅ CORRECT - Bun file API
const file = Bun.file('path/to/file.txt');
const contents = await file.text();
await Bun.write('output.txt', 'content');

// ❌ WRONG - Node.js fs
import fs from 'fs';
import { readFile } from 'fs/promises';
```

## Test Runner

**Use Bun Test, not Vitest or Jest:**

```typescript
// ✅ CORRECT - Bun Test
import { describe, test, expect } from 'bun:test';

// ❌ WRONG - Vitest/Jest imports
import { describe, test, expect } from 'vitest';
```

## Commands

**Always use Bun commands:**

```bash
✅ bun install           # Install dependencies
✅ bun run dev           # Development server
✅ bun test              # Run tests
✅ bun run build         # Build project

❌ npm install          # WRONG
❌ yarn install         # WRONG
❌ node script.js       # WRONG - use: bun run script.ts
```

## Configuration

### TypeScript Config

```json
{
  "compilerOptions": {
    "module": "Preserve",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "types": ["@types/bun"]
  }
}
```

### Bun Config (bunfig.toml)

```toml
[test]
timeout = 10000  # 10 seconds default
root = "."

[install]
# Package manager settings
```

## Native APIs

Bun provides native APIs for:
- Crypto
- Compression
- Encoding
- Streams
- Timers
- Workers
- Cron
- JWT
- Hash maps
- UUID
- Path
- Glob
- Watch
- Subprocess
- HTTP client
- WebSocket
- TLS

**Never install external packages for these features.**

## Key Files

- [Bun Config](mdc:bunfig.toml) - Runtime configuration
- [TypeScript Config](mdc:tsconfig.json) - TypeScript settings
- [Package.json](mdc:package.json) - Scripts and dependencies
- [Process Cleanup](mdc:tests/utils/process-cleanup.ts) - Process management

## Common Mistakes

### ❌ Wrong Imports

```typescript
// Don't use these
import { spawn } from 'bun';  // Wrong API
import { spawn } from 'child_process';  // Node.js
import fs from 'fs';  // Node.js
```

### ✅ Correct Imports

```typescript
// Use these
import processManager from './tests/utils/process-cleanup';
const file = Bun.file('path');
import { describe, test } from 'bun:test';
```

## Rules Summary

1. ✅ Use [processManager](mdc:tests/utils/process-cleanup.ts) for all process spawning
2. ✅ Use Bun file APIs (not Node.js fs)
3. ✅ Use Bun test runner (not Vitest/Jest)
4. ✅ Use bun commands (not npm/yarn)
5. ✅ Use Bun native APIs when available
6. ❌ Never use `Bun.spawn()` directly
7. ❌ Never use Node.js `child_process`
8. ❌ Never use Node.js `fs` module
9. ❌ Never install packages for Bun-native features