bun-runtime · v5.0.0 · 2025-10-08 · sha256 38115d196c88c1a8

bun-runtime v5.0.0A

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

---
version: "5.0.0"
scope: ["typescript", "javascript", "json", "toml"]
description: Bun runtime patterns and best practices
alwaysApply: true
lastUpdated: "2025-10-08"
dependencies: ["quality-standards", "process-management"]
---

# 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

## Related Rules

- [Process Management](mdc:.cursor/rules/process-management.mdc) - Process spawning patterns
- [Testing Patterns](mdc:.cursor/rules/testing-patterns.mdc) - Bun Test usage
- [Security Patterns](mdc:.cursor/rules/security-patterns.mdc) - Security considerations

## 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

---

## Related Rules

- [Quality Standards](mdc:.cursor/rules/quality-standards.mdc) - Code quality standards ⭐ **NEW**
- [Process Management](mdc:.cursor/rules/process-management.mdc) - Zombie process prevention
- [Testing Patterns](mdc:.cursor/rules/testing-patterns.mdc) - Bun test patterns
- [Cloudflare Workers](mdc:.cursor/rules/cloudflare-workers.mdc) - Workers with Bun

## Related Documentation

- [docs/QUALITY_STANDARDS.md](mdc:docs/QUALITY_STANDARDS.md) - Complete quality guide ⭐ **NEW**
- [tests/utils/process-cleanup.ts](mdc:tests/utils/process-cleanup.ts) - Process manager
- [bunfig.toml](mdc:bunfig.toml) - Bun configuration
- [package.json](mdc:package.json) - Project configuration
- [tsconfig.json](mdc:tsconfig.json) - TypeScript configuration

---

**Status:** Bun runtime patterns established
**Last Updated:** 2025-10-08