bun-runtime ยท v5.0.0 ยท 2025-10-08 ยท sha256 31633f571231339c

bun-runtime v5.0.0A

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

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

# Bun Runtime Rules

## ๐Ÿ” Code Searchability Patterns

### Find Bun Runtime Issues with ast-grep

```bash
# Find incorrect process spawning (should use processManager)
ast-grep --pattern 'Bun.spawn($$$)' src/
ast-grep --pattern 'import { spawn } from "bun"' src/
ast-grep --pattern 'import { spawn } from "child_process"' src/
sg -p 'Bun.spawn' src/
sg -p 'from "child_process"' src/

# Find Node.js fs usage (should use Bun file APIs)
ast-grep --pattern 'import fs from "fs"' src/
ast-grep --pattern 'import { readFile } from "fs/promises"' src/
sg -p 'from "fs"' src/
sg -p 'from "fs/promises"' src/

# Find incorrect test imports (should use bun:test)
ast-grep --pattern 'import { describe, test, expect } from "vitest"' tests/
ast-grep --pattern 'import { describe, test, expect } from "@jest/globals"' tests/
sg -p 'from "vitest"' tests/
sg -p 'from "@jest/globals"' tests/

# Find npm/yarn usage (should use bun)
ast-grep --pattern 'npm install' scripts/
ast-grep --pattern 'yarn install' scripts/
sg -p 'npm install' scripts/
sg -p 'yarn install' scripts/
```

### Bun Runtime Discovery Commands

```bash
# Find all Bun-specific patterns
sg search 'Bun.' src/
sg search 'bun:' src/
sg search 'processManager' src/

# Find Node.js anti-patterns
sg search 'from "fs"' src/
sg search 'from "child_process"' src/
sg search 'npm ' scripts/
sg search 'yarn ' scripts/

# Find Bun native APIs
sg search 'Bun.file' src/
sg search 'Bun.write' src/
sg search 'Bun.password' src/
```

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