Hono API Starter Template for Cloudflare Workers

A professional, production-ready starter template for building APIs with Hono on Cloudflare Workers. This template is designed for modern development workflows, featuring robust testing, type-safe environment management, and seamless CI/CD integration.

---

🚀 Features

• Type-Safe Environment Variables: Managed via .dev.vars and .dev.vars.test for development and testing.
• Automated Testing: Uses Vitest and @cloudflare/vitest-pool-workers for isolated, reliable tests.
• Linting & Formatting: Enforced with ESLint and Prettier for code quality and consistency.
• OpenAPI Documentation: Auto-generated using @hono/zod-openapi and available at /docs during development.
• PostgreSQL Support: Local development with PostgreSQL, production-ready for Neon Serverless.
• Modern Tooling: Built with Bun for fast installs and execution.
• CI/CD Ready: Includes a GitHub Actions workflow for linting, formatting, testing (with a Postgres service), and automated staging deployments via Wrangler.

---

�️ Getting Started

1. Clone the Repository & Install Dependencies

git clone https://github.com/ajiohjesse/HONO-API-TEMPLATE.git hono-api
cd hono-api
bun install

2. Configure Environment Variables

Copy the example environment file and update as needed:

cp .dev.vars.example .dev.vars

For test-specific variables, create a .dev.vars.test file:

cp .dev.vars.example .dev.vars.test
# Edit .dev.vars.test for your test environment

Update wrangler.jsonc with your Cloudflare account details and project configuration.

---

🐘 Database Setup

Ensure your .dev.vars or .dev.vars.test contains a valid PostgreSQL connection string (e.g., DB_URL).

To push schema and seed the database:

bun run db:push
bun run db:seed

---

🧪 Running Tests

bun run test

Tests are executed in isolated worker environments. The .dev.vars.test file is automatically loaded for test runs. The CI pipeline provisions a fresh Postgres service and sets all required environment variables for reliable, repeatable tests.

---

🧑‍💻 Development & Production Modes

The MODE environment variable controls runtime behavior:

• MODE=development|test: Uses local PostgreSQL
• Any other value: Uses Neon (serverless PostgreSQL)

---

✅ Linting & Formatting

To automatically fix lint and formatting issues:

bun run lint:fix
bun run format

To check formatting only (without writing changes):

bun run format:check

---

📚 API Documentation

Start the development server and access OpenAPI docs at http://localhost:8787/docs:

bun run dev

---

⚙️ Continuous Integration & Deployment

This project includes a GitHub Actions workflow that:

• Lints and formats code on pull requests to main
• Sets up a test environment with PostgreSQL and runs all tests
• Deploys automatically to the staging environment using Wrangler when a PR is merged

Ensure you have the required secrets (e.g., CLOUDFLARE_API_TOKEN) configured in your repository settings for deployment.

---

💡 Inspiration

Inspired by the simplicity of Hono, Cloudflare’s edge-first philosophy, and the modern developer experience enabled by Bun.

---

📜 License

MIT