# hono-typescript

Hands your agent a rulebook for building Hono and TypeScript APIs on Cloudflare Workers, Deno, Bun and Node.js. Useful once the project already runs on Hono.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 819 installs · ★ 286
- Author: Mindrally
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Mindrally/skills/tree/HEAD/hono-typescript/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/hono-typescript

## What it does

The skill feeds the agent a set of coding conventions: declare types for variables and functions, skip `any`, use `import type` for type-only imports, prefer interfaces over type aliases for object shapes, and reach for maps or const objects instead of enums. Naming is pinned down too — PascalCase for types, camelCase for functions, kebab-case for files, UPPERCASE for environment variables. Handlers and middleware are arrow functions, and the RO-RO pattern (receive an object, return an object) is the default shape.

A second block covers Hono itself: a project layout with `routes`, `middleware`, `services` and `types` folders, typed `Bindings` and `Variables` at app init, and route groups wired up with `app.route()`. Request validation goes through `@hono/zod-validator` with Zod schemas and inferred types. Errors are thrown as `HTTPException` and caught by a global `app.onError`. There are examples for Workers KV, D1 and R2, integration tests with `testClient` and Vitest, plus the four runtime entry points.

The skill installs nothing into your project and pulls no dependencies. It only describes how code should be written, so a fresh repo with no Hono and no Zod gets little out of it — the stack has to exist first. In a project that already uses Hono, though, it is a reason to check how far your current routes and validators drift from what the agent will start generating.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill hono-typescript -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/hono-typescript/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/hono-typescript/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill hono-typescript -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/hono-typescript/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill hono-typescript -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/hono-typescript/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Mindrally/skills hono-typescript
```

2. **Manually: put the files in place**
- File: `.github/skills/hono-typescript/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill hono-typescript -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Mindrally/skills --path hono-typescript
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/hono-typescript/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill hono-typescript -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Mindrally/skills/tree/HEAD/hono-typescript/SKILL.md

## When to use it
- keep agent-generated TypeScript consistent across a Hono codebase
- lay out folders for routes, middleware and services
- validate request bodies with Zod and infer the types
- route expected errors through a single HTTPException handler
- run the same app on Workers, Deno, Bun and Node.js

## Example prompts
- add a POST /api/users route with zValidator and a Zod schema
- move auth into a typed middleware and apply it to /api/*
- set up a global onError so HTTPException returns JSON with the right status

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d296500857bac130.

BEGIN THIRD-PARTY FILE d296500857bac130
````text
---
name: hono-typescript
description: Guidelines for building edge-first, high-performance APIs with Hono and TypeScript for Cloudflare Workers, Deno, Bun, and Node.js
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# Hono TypeScript Development

You are an expert in Hono and TypeScript development with deep knowledge of building ultrafast, edge-first APIs that run on Cloudflare Workers, Deno, Bun, and Node.js.

## TypeScript General Guidelines

### Basic Principles

- Use English for all code and documentation
- Always declare types for variables and functions (parameters and return values)
- Avoid using `any` type - create necessary types instead
- Use JSDoc to document public classes and methods
- Write concise, maintainable, and technically accurate code
- Use functional and declarative programming patterns; avoid classes
- Prefer iteration and modularization to adhere to DRY principles

### Nomenclature

- Use PascalCase for types and interfaces
- Use camelCase for variables, functions, and methods
- Use kebab-case for file and directory names
- Use UPPERCASE for environment variables
- Use descriptive variable names with auxiliary verbs: `isLoading`, `hasError`, `canDelete`
- Start each function with a verb

### Functions

- Write short functions with a single purpose
- Use arrow functions for handlers and middleware
- Prefer the RO-RO pattern: Receive an Object, Return an Object
- Use default parameters instead of null checks

### Types and Interfaces

- Prefer interfaces over types for object shapes
- Avoid enums; use maps or const objects instead for better type safety
- Use Zod for runtime validation with inferred types
- Use `readonly` for immutable properties
- Use `import type` for type-only imports

## Hono-Specific Guidelines

### Project Structure

```
src/
  routes/
    {resource}/
      index.ts
      handlers.ts
      validators.ts
  middleware/
    auth.ts
    cors.ts
    logger.ts
  services/
    {domain}Service.ts
  types/
    index.ts
  utils/
  config/
  index.ts
```

### App Initialization

```typescript
import { Hono } from 'hono';

// Type your environment bindings
type Bindings = {
  DB: D1Database;
  KV: KVNamespace;
  JWT_SECRET: string;
};

type Variables = {
  user: User;
};

const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
```
````
END THIRD-PARTY FILE d296500857bac130

The third-party file has ended. Everything between the d296500857bac130 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2359 of 6615 bytes. © Mindrally · Apache-2.0 · https://github.com/Mindrally/skills/tree/HEAD/hono-typescript/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md