Why use bun:sqlite instead of better-sqlite3 or node:sqlite?

bun:sqlite is a native binding built into the Bun runtime with no native compilation step, and it benchmarks faster than better-sqlite3 for most workloads. It shares the same synchronous API shape, so swapping in Turso's @libsql/client for edge replication later requires minimal code changes.

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard supported by 30+ coding agents including Cursor, Claude Code, and Windsurf. A dedicated .mdc file is also provided for Cursor's native .cursor/rules format.

Why does WAL mode matter for a Bun + SQLite API?

Write-Ahead Logging lets readers and a single writer operate concurrently instead of locking the whole database file, which matters under Bun's high request throughput. Without WAL, concurrent requests hitting SQLite will serialize and can produce SQLITE_BUSY errors under load.

Bun + Hono + SQLite AGENTS.md, Cursor Rules & Skills

Architecture Overview

Production-ready architectural guidelines for Bun, Hono v4, SQLite, and Drizzle ORM.

Key Advantages

Sub-Millisecond Response Times: Bun’s native C/Zig bindings combined with Hono’s lightweight RegExpRouter deliver microsecond latency overhead.
Embedded & Edge Ready: Zero-configuration embedded SQLite via bun:sqlite or distributed edge replication via Turso libSQL.
End-to-End Type Safety: Hono RPC allows sharing backend route types directly with frontend clients without code generation.

1	# Project Architecture & Guidelines (Bun + Hono + SQLite / Drizzle)
2
3	## 1. System Architecture
4	- Runtime: Bun (Bun.serve() high-performance HTTP & WebSocket server).
5	- Web Framework: Hono v4 (`hono`, `@hono/zod-validator`).
6	- Database & ORM: SQLite (`bun:sqlite` or `@libsql/client` for Turso edge replication) via Drizzle ORM.
7	- Type Validation: Zod with `@hono/zod-openapi` for declarative request/response contracts and automatic Swagger documentation.
8
9	## 2. Monorepo & Modular File Layout
10	- `src/index.ts`: Application bootstrap and `export default app` for Bun.serve().
11	- `src/routes/`: Route modules using `new Hono()`, grouped by domain entity (e.g. `users.routes.ts`, `auth.routes.ts`).
12	- `src/db/`:
13	- `schema.ts`: Drizzle table definitions using `sqliteTable()`.
14	- `client.ts`: Singleton database connection pool.
15	- `src/middleware/`: Bearer token auth, CORS, logger, and global error boundaries.
16
17	## 3. Route Handlers & Zod Validation
18	- Validate query, params, and JSON bodies strictly with `zValidator('json', schema)` or `@hono/zod-openapi`.
19	- Never parse `c.req.json()` manually without prior schema validation.
20	- Return typed JSON responses via `c.json({ success: true, data })`.
21
22	## 4. Database & Transaction Rules
23	- Use Drizzle ORM prepared queries for hot paths.
24	- Enable Write-Ahead Logging (`PRAGMA journal_mode = WAL;`) and busy timeouts (`PRAGMA busy_timeout = 5000;`) on SQLite databases.
25	- Group multi-row mutations inside `db.transaction()` blocks to prevent partial writes.
26
27	## 5. Coding Standards & Error Handling
28	- Strict TypeScript: `strict: true`, zero `any` policy.
29	- Throw typed `HTTPException` from `hono/http-exception` with explicit HTTP status codes (400, 401, 404, 422).
30	- Register global `app.onError((err, c) => ...)` returning consistent JSON error envelopes `{ error: string, code?: string }`.
31
32	## 6. Testing Conventions
33	- Use Bun's native test runner (`bun test`) — no Jest/Vitest dependency needed.
34	- Test Hono routes with `app.request('/path', { method: 'POST', body })` against an in-memory SQLite database, never the production file.
35	- Cover Zod schema edge cases explicitly (missing fields, wrong types, boundary values) — validation bugs are the most common regression in this stack.
36	- Run `bun test --coverage` in CI; block merges that drop coverage on `src/routes/` or `src/db/`.
37
38	## 7. Git Workflow & PR Conventions
39	- Conventional Commits (`feat:`, `fix:`, `refactor:`) with the affected route/module in scope, e.g. `fix(auth): handle expired bearer tokens`.
40	- Every PR that changes `src/db/schema.ts` must include the generated Drizzle migration file in the same commit.
41	- Require `bun test` and `tsc --noEmit` to pass before merge; no exceptions for "just a typo fix" PRs touching schema files.
42	- Rebase onto `main` before merging; keep history linear for easy `bun run db:migrate` rollback tracing.

Bun + Hono + SQLite (libSQL & Drizzle ORM)

Architecture Overview

Key Advantages

Why use bun:sqlite instead of better-sqlite3 or node:sqlite?

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Why does WAL mode matter for a Bun + SQLite API?

Astro SSR + Tailwind CSS + Cloudflare

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Go + Echo + SQLite (Embedded, Self-Hosted Tools)

Go + PostgreSQL (pgx & sqlc) + React

Bun + Hono + SQLite (libSQL & Drizzle ORM)

Architecture Overview

Key Advantages

Why use bun:sqlite instead of better-sqlite3 or node:sqlite?

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Why does WAL mode matter for a Bun + SQLite API?

Grafana

tRPC

Prisma

Bun

Astro SSR + Tailwind CSS + Cloudflare

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Go + Echo + SQLite (Embedded, Self-Hosted Tools)

Go + PostgreSQL (pgx & sqlc) + React