Esmi API

Type-safe JSON API built with Hono, OpenAPI, Drizzle ORM, and Better Auth. Runs locally via Cloudflare Wrangler with Node.js compatibility.

Features

• OpenAPI docs: @hono/zod-openapi + Scalar UI
• Auth: Better Auth routes proxied under /api/auth/*
• Database: PostgreSQL via Drizzle ORM
• Logging: Pino + hono-pino

Quick start

Prerequisites

• Node.js 20+
• Bun (for bunx used by db scripts)
• Cloudflare Wrangler (npm i -g wrangler)
• A PostgreSQL database (e.g. Neon) and DATABASE_URL

Install

npm install

Environment

Create a .env file with:

NODE_ENV=development
LOG_LEVEL=info
DATABASE_URL=postgres://user:pass@host/db
# Only required in production when using Neon auth token
DATABASE_AUTH_TOKEN=

BETTER_AUTH_SECRET=replace-me
BETTER_AUTH_URL=http://localhost:8787
BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000

# OAuth (Google) for Better Auth
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=

Database

Generate and run migrations:

npm run db:generate
npm run db:migrate

Optional seed:

npm run db:seed

Run locally

npm run dev
# Wrangler serves on http://localhost:8787 by default

Build & deploy

npm run build
npm run deploy

API

Docs

• GET /doc OpenAPI spec (JSON)
• GET /reference Scalar API UI

Auth

• GET|POST /api/auth/* handled by Better Auth

Index

• GET / health/info

Organizations (requires auth)

• GET /organizations/{ownerId} list organizations for a user
• POST /organizations create organization
• PATCH /organizations/{id} update by id
• DELETE /organizations/{id} delete by id

Leagues

• GET /leagues/{locationId} list leagues for a location

Marketing

• GET /marketing/email list email signups
• POST /marketing/email create email signup

Tags

• GET /tags?type={type} list tags (optional filter by type)

Project structure

• App bootstrap: src/app.ts
• OpenAPI config & UI: src/lib/configure-open-api.ts
• Routes: src/routes/**
• DB schema: src/db/schema/**
• Drizzle config: drizzle.config.ts

For the current database model overview, see DB_SCHEMA.md.

Scripts

• dev: Wrangler dev server
• build: TypeScript build + path aliasing
• deploy: Wrangler deploy
• test: Vitest
• lint / lint:fix
• db:generate / db:migrate / db:studio / db:seed