# Hono Cloudflare

> Hono + Cloudflare Workers Skill

- Skill: `quannv1198/hono-cloudflare` (Agent Skill)
- Install (CLI): `npx skillmds@latest add quannv1198/hono-cloudflare`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quannv1198/hono-cloudflare/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: quannv1198 (https://skillmd.com/u/quannv1198)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/quannv1198/hono-cloudflare

---

# Hono + Cloudflare Workers Skill

Build robust, scalable, and maintainable backend services using Hono and Cloudflare Workers.

## Core Principles

* Follow the existing project architecture, conventions, and Cloudflare configuration.
* Prefer Cloudflare Workers-native APIs and services over Node.js-specific APIs.
* Keep handlers small, focused, and easy to test.
* Separate routing, business logic, validation, and data access when appropriate.
* Prefer simple solutions over unnecessary abstractions.
* Reuse existing utilities, middleware, schemas, and services.

## Hono

* Use Hono routing and middleware consistently.
* Keep route handlers focused on HTTP concerns.
* Use Hono context (`c`) correctly for request, response, environment bindings, and variables.
* Prefer middleware for cross-cutting concerns such as authentication, logging, CORS, and error handling.
* Validate request parameters, query strings, headers, and bodies before using them.
* Return appropriate HTTP status codes and consistent response formats.
* Keep API error responses predictable and useful.
* Avoid putting complex business logic directly inside route handlers.

## Cloudflare Workers

* Follow the Workers runtime model and avoid Node.js-only APIs.
* Use `env` bindings for environment variables, secrets, KV, R2, D1, Durable Objects, Queues, and other Cloudflare services.
* Never hardcode secrets, API keys, tokens, or credentials.
* Prefer asynchronous APIs and avoid blocking operations.
* Consider Worker execution limits and request lifecycle when designing backend logic.
* Use `waitUntil()` for non-critical background work when appropriate.
* Handle external API failures, timeouts, and unexpected responses safely.

## Environment and Bindings

* Inspect `wrangler.jsonc`, `wrangler.toml`, or existing Cloudflare configuration before changing bindings.
* Reuse existing bindings instead of creating duplicates.
* Keep local, preview, and production environments clearly separated.
* Do not modify Cloudflare configuration unless required by the task.
* Ensure new bindings are correctly typed in the project's environment types.

## API Design

* Use consistent URL patterns and HTTP methods.
* Validate all external input.
* Return clear and predictable JSON responses.
* Use proper status codes for success, validation errors, authentication failures, authorization failures, not-found cases, conflicts, and server errors.
* Avoid leaking internal errors, secrets, stack traces, or implementation details.
* Design APIs to be backward-compatible when possible.

## Security

* Treat all client input as untrusted.
* Validate and sanitize input at the API boundary.
* Authenticate and authorize protected endpoints.
* Never expose secrets or sensitive environment variables in responses.
* Protect against common API issues such as injection, broken authorization, excessive payloads, and abuse.
* Configure CORS deliberately instead of allowing unrestricted origins unless required.
* Apply rate limiting or Cloudflare-native protection when appropriate.

## Database and Storage

* Reuse existing database and storage patterns.
* Use D1 for relational data, KV for simple key-value data, R2 for object storage, and Durable Objects for stateful coordination when appropriate.
* Avoid unnecessary database queries.
* Use parameterized queries.
* Handle transactions and concurrent updates correctly.
* Consider indexes and query performance when working with D1.

## External APIs

* Validate external API responses instead of assuming their structure.
* Handle timeouts, rate limits, retries, and transient failures appropriately.
* Avoid unnecessary external requests.
* Do not expose third-party credentials to clients.
* Keep external API integrations isolated from route handlers when practical.

## Error Handling

* Use centralized error handling when the project supports it.
* Return consistent error responses.
* Log useful diagnostic information without logging secrets or sensitive data.
* Distinguish expected client errors from unexpected server errors.
* Never silently ignore failures.

## Implementation Rules

* Inspect existing routes, middleware, services, schemas, and bindings before implementing changes.
* Search for similar endpoints and reuse established patterns.
* Make the smallest necessary changes.
* Avoid unrelated refactoring.
* Do not invent Cloudflare bindings, APIs, or runtime capabilities.
* Check the installed versions of Hono, Wrangler, and relevant Cloudflare packages before using newer APIs.
* Prefer existing project dependencies over adding new ones.
* Keep types accurate and avoid `any`.

## Verification

After making changes, run available checks such as:

* TypeScript type checking
* Linting
* Unit or integration tests
* Wrangler validation
* Build or deployment checks when appropriate

Verify both successful and failure paths for API changes.

## Avoid

* Node.js APIs that are unavailable in the Workers runtime.
* Hardcoded secrets or credentials.
* Unvalidated request data.
* Business logic scattered across route handlers.
* Unnecessary middleware.
* Unnecessary database queries.
* Unnecessary external API calls.
* Catching errors without handling or logging them.
* Large architectural changes for small feature requests.