CLAUDE.md

Agent Guidelines for this project

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Bun automatically loads .env, so don't use dotenv.

APIs

• Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Bun.sql for Postgres. Don't use pg or postgres.js.
• WebSocket is built-in. Don't use ws.
• Prefer Bun.file over node:fs's readFile/writeFile
• Bun.$ls instead of execa.

Testing

Use bun test to run tests.

import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});

For more information, read the Bun API docs in node_modules/bun-types/docs/**.md.

Build/Test Commands

• bun test - Run all tests
• bun test <file> - Run specific test file (e.g., bun test src/animation/Timeline.test.ts)
• cd src/zig && zig build - Build Zig components (production)
• cd src/zig && zig build -Doptimize=Debug - Build Zig components (debug)
• cd src/zig && zig build -Doptimize=ReleaseFast - Build Zig components (optimized)

Code Style

• Runtime: Bun with TypeScript
• Formatting: Prettier (semi: false, printWidth: 120)
• Imports: Use explicit imports, group by: built-ins, external deps, internal modules
• Types: Strict TypeScript, use interfaces for options/configs, explicit return types for public APIs
• Naming: camelCase for variables/functions, PascalCase for classes/interfaces, UPPER_CASE for constants
• Error Handling: Use proper Error objects, avoid silent failures
• Async: Prefer async/await over Promises, handle errors explicitly
• Comments: Minimal comments, focus on JSDoc for public APIs only
• File Structure: Index files for clean exports, group related functionality
• Testing: Bun test framework, descriptive test names, use beforeEach/afterEach for setup

Took this from https://github.com/sst/opentui/blob/main/AGENTS.md

Useful in any projects with bun