Bun + Hono + SQLite (libSQL & Drizzle ORM)

Curated rule Developer Tool & API Updated Sep 2026 Which file does my tool read?

Ultra-fast edge API architecture using Bun.serve(), Hono v4, Drizzle ORM with embedded SQLite / Turso libSQL, and Zod OpenAPI validation.

Bun Hono SQLite Drizzle TypeScript Zod

Formats: 4 files
AGENTS.md: 42 lines
CLAUDE.md: 16 lines
Languages: TypeScript
Updated: Sep 2026
Used by: 4 projects

Install

Writes .claude/skills/bun-hono-sqlite/SKILL.md

$ curl -s --create-dirs -o .claude/skills/bun-hono-sqlite/SKILL.md https://stackitfast.com/rules/bun-hono-sqlite/SKILL.md

Rule files

AGENTS.md· 42 lines · 2.8 KB

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.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

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.

Frequently asked questions

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.

Used in production

Explore all stacks

Gotify

Self-Hosted Real-Time Push Server · 2-5 People

Gotify keeps the server one deployable Go binary by embedding its Vite/React web UI, using Gin and gorilla/websocket for the REST and streaming API, and swapping SQLite, MySQL or PostgreSQL through GORM, while a compiled Go plugin system handles extensibility instead of a scripting layer.

elekcsv

Headless CSV Ingestion Engine · Solo

Keeping parsing, compiled-validator generation, fuzzy column mapping and bitmap error tracking in one dependency-free core package lets every UI framework reuse identical import logic instead of six separate implementations.

Orca

Agentic Development Environment for Parallel Coding Agents · 6-20 people

Agent CLIs stay the user's own. Orca adds the orchestration layer around them: isolated git worktrees, a PTY daemon that outlives the UI, and a relay for mobile steering. It can support new agents without bundling them.

MindsHub (formerly MindsDB)

Desktop & Web AI Agent Workspace · 20+ People

Splitting the client, API and agent into separately versioned git submodules lets each ship on its own cadence (a signed desktop app, a PyPI server package, an agent package), while one Makefile and one docker-compose.yml still bring the whole stack up together.

Where this stack fits

Stack It First recommends it at:

Backend · MVP · Internal Backend · MVP · Product API

Walk the backend roadmap

Every stack ships as files

More AI agent coding rules and skills

View all

astro-static-content/AGENTS.mdAstro Static Site + Content Collections + TailwindAstro · Tailwind CSS · TypeScript fastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQL go-echo-sqlite/AGENTS.mdGo + Echo + SQLite (Embedded, Self-Hosted Tools)Go · Echo · SQLite astro-tailwind-cloudflare/AGENTS.mdAstro SSR + Tailwind CSS + CloudflareAstro · Tailwind CSS · Cloudflare