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.
- Type-Safe Environment Variables: Managed via
.dev.varsand.dev.vars.testfor 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-openapiand available at/docsduring 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.
git clone https://github.com/ajiohjesse/HONO-API-TEMPLATE.git hono-api
cd hono-api
bun installCopy the example environment file and update as needed:
cp .dev.vars.example .dev.varsFor test-specific variables, create a .dev.vars.test file:
cp .dev.vars.example .dev.vars.test
# Edit .dev.vars.test for your test environmentUpdate wrangler.jsonc with your Cloudflare account details and project configuration.
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:seedbun run testTests 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.
The MODE environment variable controls runtime behavior:
MODE=development|test: Uses local PostgreSQL- Any other value: Uses Neon (serverless PostgreSQL)
To automatically fix lint and formatting issues:
bun run lint:fix
bun run formatTo check formatting only (without writing changes):
bun run format:checkStart the development server and access OpenAPI docs at http://localhost:8787/docs:
bun run devThis 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.
Inspired by the simplicity of Hono, Cloudflare’s edge-first philosophy, and the modern developer experience enabled by Bun.
MIT