bun-runtime · git:20251007.d4e620d · 2025-10-07 · sha256 e9cd34aae416b07b
bun-runtime git:20251007.d4e620dA
Immutable. This exact content never changes and is served at /api/v1/blob/e9cd34aae416b07b.
---
alwaysApply: true
description: Bun runtime requirements and conventions
---
# Bun Runtime Rules
## Runtime Choice
**This project uses Bun exclusively** - not Node.js, not npm, not yarn.
### 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";
describe("my test", () => {
test("should work", () => {
expect(true).toBe(true);
});
});
// ❌ WRONG: Vitest/Jest imports
import { describe, test, expect } from "vitest";
import { describe, test, expect } from "@jest/globals";
```
### File System Operations
**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");
// ❌ WRONG: Node.js fs
import fs from "fs";
import { readFile } from "fs/promises";
```
### Configuration
- TypeScript config uses `moduleResolution: "bundler"`
- Project configured in [bunfig.toml](mdc:config/bunfig.toml)
- See [package.json](mdc:package.json) for available Bun scripts
### Why Bun?
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."
**Never suggest installing external packages for functionality that Bun provides natively.**