CLAUDE.md

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>
• Use bunx <package> <command> instead of npx <package> <command>
• 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);
});

Architecture

This app will use a modular architecture setup:

/project-root
├── /src
│   ├── /core             <-- INTERNAL ONLY. The engine room.
│   │   ├── client.ts     # The actual HTTP wrapper / Context holder
│   │   ├── config.ts     # Validation logic for SDK init
│   │   ├── auth.ts       # Token refresh / headers logic
│   │   └── errors.ts     # Custom error classes
│   │
│   ├── /modules          <-- PUBLIC DOMAINS. Standalone feature sets.
│   │   ├── /users
│   │   │   ├── index.ts  # Barrel file for 'users'
│   │   │   ├── list.ts   # Functional export: getUsers()
│   │   │   ├── get.ts    # Functional export: getUser()
│   │   │   └── types.ts  # Types specific to users
│   │   │
│   │   ├── /analytics
│   │   │   ├── index.ts
│   │   │   └── track.ts
│   │
│   ├── /types            <-- SHARED TYPES.
│   │   └── index.ts      # Common interfaces (ClientOptions, Pagination)
│   │
│   └── index.ts          <-- MAIN ENTRY. Exports createClient and types.
│
├── package.json          <-- CRITICAL. Defines subpath exports.
├── tsconfig.json
└── tsup.config.ts        # (Or rollup/vite) Build configuration

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