README.md

Hono Open API Starter

A starter template for building fully documented type-safe JSON APIs with Hono and Open API.

A new version of drizzle was released since the video showing this starter was made. See the drizzle-v0.35 branch and this commit for the changes required to use drizzle v0.35

For a cloudflare specific template, see the cloudflare branch on this repo and the cloudflare-drizzle-v0.35 branch

For other deployment examples see the hono-node-deployment-examples repo

• Hono Open API Starter
  • Included
  • Setup
  • Code Tour
  • Endpoints
  • References

Included

• Structured logging with pino / hono-pino
• Documented / type-safe routes with @hono/zod-openapi
• Interactive API documentation with scalar / @scalar/hono-api-reference
• Convenience methods / helpers to reduce boilerplate with stoker
• Type-safe schemas and environment variables with zod
• Single source of truth database schemas with drizzle and drizzle-zod
• Testing with vitest
• Sensible editor, formatting and linting settings with @antfu/eslint-config

Setup

Clone this template without git history

npx degit w3cj/hono-open-api-starter my-api
cd my-api

Create .env file

cp .env.example .env

Install dependencies

pnpm install

Create sqlite db / push schema

pnpm drizzle-kit push

Run

pnpm dev

Lint

pnpm lint

Test

pnpm test

Code Tour

Base hono app exported from app.ts. Local development uses @hono/node-server defined in index.ts - update this file or create a new entry point to use your preferred runtime.

Typesafe env defined in env.ts - add any other required environment variables here. The application will not start if any required environment variables are missing

See src/routes/tasks for an example Open API group. Copy this folder / use as an example for your route groups.

• Router created in tasks.index.ts
• Route definitions defined in tasks.routes.ts
• Hono request handlers defined in tasks.handlers.ts
• Group unit tests defined in tasks.test.ts

All app routes are grouped together and exported into single type as AppType in app.ts for use in RPC / hono/client.

Endpoints

Path	Description
GET /doc	Open API Specification
GET /reference	Scalar API Documentation
GET /tasks	List all tasks
POST /tasks	Create a task
GET /tasks/{id}	Get one task by id
PATCH /tasks/{id}	Patch one task by id
DELETE /tasks/{id}	Delete one task by id

References

• What is Open API?
• Hono
  • Zod OpenAPI Example
  • Testing
  • Testing Helper
• @hono/zod-openapi
• Scalar Documentation
  • Themes / Layout
  • Configuration