bun-runtime · diff
v4 to v5.0.0
25 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
- version: 4
+ 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