---
name: bun-hono-sqlite
description: "Use when building, refactoring, or reviewing a Bun + Hono + SQLite (libSQL & Drizzle ORM) project (Bun, Hono, SQLite, Drizzle, TypeScript, Zod). Ultra-fast edge API architecture using Bun.serve(), Hono v4, Drizzle ORM with embedded SQLite / Turso libSQL, and Zod OpenAPI validation."
license: MIT
metadata:
  source: https://stackitfast.com/rules/bun-hono-sqlite
  version: "2026-09-10"
---

# Bun + Hono + SQLite (libSQL & Drizzle ORM) — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a Bun + Hono + SQLite (libSQL & Drizzle ORM) codebase.
- Whenever the project depends on Bun, Hono, SQLite, Drizzle, TypeScript, Zod.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (Bun + Hono + SQLite / Drizzle)

## 1. System Architecture
- **Runtime**: Bun (Bun.serve() high-performance HTTP & WebSocket server).
- **Web Framework**: Hono v4 (`hono`, `@hono/zod-validator`).
- **Database & ORM**: SQLite (`bun:sqlite` or `@libsql/client` for Turso edge replication) via Drizzle ORM.
- **Type Validation**: Zod with `@hono/zod-openapi` for declarative request/response contracts and automatic Swagger documentation.

## 2. Monorepo & Modular File Layout
- `src/index.ts`: Application bootstrap and `export default app` for Bun.serve().
- `src/routes/`: Route modules using `new Hono()`, grouped by domain entity (e.g. `users.routes.ts`, `auth.routes.ts`).
- `src/db/`:
  - `schema.ts`: Drizzle table definitions using `sqliteTable()`.
  - `client.ts`: Singleton database connection pool.
- `src/middleware/`: Bearer token auth, CORS, logger, and global error boundaries.

## 3. Route Handlers & Zod Validation
- Validate query, params, and JSON bodies strictly with `zValidator('json', schema)` or `@hono/zod-openapi`.
- Never parse `c.req.json()` manually without prior schema validation.
- Return typed JSON responses via `c.json({ success: true, data })`.

## 4. Database & Transaction Rules
- Use Drizzle ORM prepared queries for hot paths.
- Enable Write-Ahead Logging (`PRAGMA journal_mode = WAL;`) and busy timeouts (`PRAGMA busy_timeout = 5000;`) on SQLite databases.
- Group multi-row mutations inside `db.transaction()` blocks to prevent partial writes.

## 5. Coding Standards & Error Handling
- Strict TypeScript: `strict: true`, zero `any` policy.
- Throw typed `HTTPException` from `hono/http-exception` with explicit HTTP status codes (400, 401, 404, 422).
- Register global `app.onError((err, c) => ...)` returning consistent JSON error envelopes `{ error: string, code?: string }`.

## 6. Testing Conventions
- Use Bun's native test runner (`bun test`) — no Jest/Vitest dependency needed.
- Test Hono routes with `app.request('/path', { method: 'POST', body })` against an in-memory SQLite database, never the production file.
- Cover Zod schema edge cases explicitly (missing fields, wrong types, boundary values) — validation bugs are the most common regression in this stack.
- Run `bun test --coverage` in CI; block merges that drop coverage on `src/routes/` or `src/db/`.

## 7. Git Workflow & PR Conventions
- Conventional Commits (`feat:`, `fix:`, `refactor:`) with the affected route/module in scope, e.g. `fix(auth): handle expired bearer tokens`.
- Every PR that changes `src/db/schema.ts` must include the generated Drizzle migration file in the same commit.
- Require `bun test` and `tsc --noEmit` to pass before merge; no exceptions for "just a typo fix" PRs touching schema files.
- Rebase onto `main` before merging; keep history linear for easy `bun run db:migrate` rollback tracing.

## Source
Maintained at https://stackitfast.com/rules/bun-hono-sqlite — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.