bun-runtime · diff
git:20251007.d4e620d to git:20251007.8d64d27
124 added, 38 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.
---
+ description: Bun runtime patterns and best practices
alwaysApply: true
- description: Bun runtime requirements and conventions
---
# Bun Runtime Rules
- ## Runtime Choice
+ ## Process Spawning (CRITICAL)
- **This project uses Bun exclusively** - not Node.js, not npm, not yarn.
+ ### Always Use Process Manager
- ### Commands
+ ```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
- ✅ bun run lint # Lint code
- ✅ bun run format # Format code
❌ npm install # WRONG
- ❌ npm run dev # WRONG
❌ yarn install # WRONG
❌ node script.js # WRONG - use: bun run script.ts
```
- ### Test Runner
-
- **Use Bun Test, not Vitest or Jest:**
- ```typescript
- // ✅ CORRECT: Bun Test
- import { describe, test, expect } from "bun:test";
+ ## Configuration
- describe("my test", () => {
- test("should work", () => {
- expect(true).toBe(true);
- });
- });
+ ### TypeScript Config
- // ❌ WRONG: Vitest/Jest imports
- import { describe, test, expect } from "vitest";
- import { describe, test, expect } from "@jest/globals";
+ ```json
+ {
+ "compilerOptions": {
+ "module": "Preserve",
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": true,
+ "noEmit": true,
+ "types": ["@types/bun"]
+ }
+ }
```
- ### File System Operations
+ ### Bun Config (bunfig.toml)
- **Use Bun APIs, not Node.js fs module:**
- ```typescript
- // ✅ CORRECT: Bun file API
- const file = Bun.file("path/to/file.txt");
- const contents = await file.text();
- await Bun.write("output.txt", "content");
+ ```toml
+ [test]
+ timeout = 10000 # 10 seconds default
+ root = "."
- // ❌ WRONG: Node.js fs
- import fs from "fs";
- import { readFile } from "fs/promises";
+ [install]
+ # Package manager settings
```
- ### Configuration
+ ## Native APIs
- - TypeScript config uses `moduleResolution: "bundler"`
- - Project configured in [bunfig.toml](mdc:config/bunfig.toml)
- - See [package.json](mdc:package.json) for available Bun scripts
+ Bun provides native APIs for:
+ - Crypto
+ - Compression
+ - Encoding
+ - Streams
+ - Timers
+ - Workers
+ - Cron
+ - JWT
+ - Hash maps
+ - UUID
+ - Path
+ - Glob
+ - Watch
+ - Subprocess
+ - HTTP client
+ - WebSocket
+ - TLS
- ### Why Bun?
+ **Never install external packages for these features.**
- From project memory: "This project uses 100% Bun-native APIs for features such as crypto, compression, encoding, streams, timers, workers, cron, JWT, hash maps, UUID, path, glob, watch, subprocess, HTTP client, WebSocket client, and TLS."
+ ## Key Files
- **Never suggest installing external packages for functionality that Bun provides natively.**
+ - [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