playbooks

home / skills / joncrangle / .dotfiles / hono

hono skill

/dot_config/opencode/skills/hono

This skill helps you implement high performance Hono endpoints with type-safe RPC, edge-ready middleware, and runtime validation across runtimes.

npx playbooks add skill joncrangle/.dotfiles --skill hono

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.3 KB
---
name: hono
description: Specialist in Hono (v4+), an ultrafast web framework for Edge (Cloudflare, Bun, Deno) and Node. Focuses on type-safe RPC, middleware, and Web Standards.
---
<skill_doc>
<trigger_keywords>
## Trigger Keywords

Activate this skill when the user mentions any of:

**Core**: Hono, c (Context), app.get, app.post, app.use, hono/jsx

**RPC / Types**: zValidator, hono/client, hc, AppType, client.index.$get

**Environments**: Cloudflare Workers, Bun, Deno, Edge, c.env, Bindings

**Testing**: app.request, testClient
</trigger_keywords>

## ⛔ Forbidden Patterns

1.  **NO Node.js Specifics on Edge**: Avoid `fs`, `path`, or `process` when targeting Cloudflare/Deno.
2.  **NO Untyped Validators**: Don't use `c.req.json()` raw if you have `zValidator`. Use `c.req.valid('json')`.
3.  **NO Controller Classes**: Avoid OOP-style controller classes. They break Hono RPC type inference. Use inline handlers or `factory.createHandlers`.
4.  **NO `res.send`**: This is not Express. Return `c.json()`, `c.text()`, or a `Response` object.
5.  **NO Global State**: In serverless/edge, global variables may not persist. Use `c.set/c.get` for request-scoped state or `c.env` for config.

## 🤖 Agent Tool Strategy

1.  **Runtime Check**: Identify the target runtime (Cloudflare, Bun, Node) to recommend correct bindings and adapters.
2.  **RPC First**: Suggest Hono RPC (`client`) for frontend-backend communication to share types automatically.
3.  **Validation**: Always pair inputs with `@hono/zod-validator` for runtime safety and type inference.
4.  **Testing**: Prefer `app.request()` for fast integration tests over spinning up a localhost server.

## Quick Reference (30 seconds)

Hono Specialist - Ultrafast, Standards-based, Multi-runtime.

**Core Philosophy**:
- **Web Standards**: Built on `Request` and `Response`.
- **RegExpRouter**: Extremely fast routing engine.
- **Type-Safe RPC**: Share `AppType` with client for autocompletion.

**Context (`c`)**:
- `c.req`: Request object.
- `c.env`: Environment variables/bindings.
- `c.json()`: Send JSON response.
- `c.var`: Request-scoped variables (middleware).

---

## Resources

- **Examples**: See `examples/examples.md` for detailed code patterns.
- **References**: See `references/reference.md` for official documentation links.
</skill_doc>

Overview

This skill specializes in Hono (v4+) — an ultrafast, standards-based web framework for Edge and Node runtimes. It focuses on type-safe RPC, middleware patterns, and multi-runtime deployment (Cloudflare Workers, Bun, Deno). The guidance emphasizes predictable request handling, validators, and test-friendly patterns for reliable edge services.

How this skill works

The skill inspects code and intent to identify target runtime and recommends correct adapters and binding usage. It favors Hono RPC (client + AppType) to share types between server and client, and enforces @hono/zod-validator usage for runtime-safe inputs. It flags runtime anti-patterns for Edge environments and suggests app.request() for fast integration testing.

When to use it

  • Building edge-first APIs for Cloudflare Workers, Bun, or Deno.
  • Creating type-safe RPC endpoints shared between frontend and backend.
  • Adding middleware that needs request-scoped state or validation.
  • Writing fast integration tests without running a full server.
  • Migrating Express-style code to Web Standards-based Hono handlers.

Best practices

  • Detect the runtime (Cloudflare/Bun/Deno/Node) first and pick the correct adapter and bindings.
  • Use Hono RPC (client + AppType) to auto-share types and reduce runtime errors.
  • Always validate inputs with @hono/zod-validator and prefer c.req.valid('json') over raw parsing.
  • Avoid Node-only APIs (fs, path, process) when targeting Edge runtimes.
  • Return responses with c.json()/c.text() or a Response object; do not use Express patterns like res.send.
  • Keep no global mutable state; use c.set/c.get for request-scoped variables and c.env for config/bindings.

Example use cases

  • Implementing a type-safe RPC endpoint that auto-generates client methods for a SPA.
  • Deploying a tiny edge function on Cloudflare that uses bindings from c.env and no filesystem access.
  • Writing middleware to attach request-scoped auth info via c.set and reading it later in handlers.
  • Converting Express controllers to Hono-style inline handlers or factory.createHandlers for better type inference.
  • Running unit and integration tests using app.request() and testClient instead of spinning up a server.

FAQ

Can I use Node fs or path in Edge deployments?

No. Avoid fs/path/process when targeting Cloudflare, Deno, or other Edge runtimes; use bindings and c.env instead.

How should I parse and validate JSON input?

Use @hono/zod-validator and call c.req.valid('json') or zValidator so you get runtime checks and type inference; do not call c.req.json() raw.

Why avoid controller classes?

OOP controller classes break Hono RPC type inference. Use inline handlers or factory.createHandlers to keep types intact.