w3cj/hono-open-api-starter

README

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 this commit for the changes required to use drizzle v0.35+

A new version of zod was released since the video showing this starter was made. See this commit for the changes required to use zod v4.

For a cloudflare specific template, see the cloudflare branch on this repo

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