hono-typescript

SKILL.md

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

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 }>();

Routing

Use method chaining for clean route definitions

Group related routes with app.route()

Use route parameters with proper typing

const users = new Hono<{ Bindings: Bindings }>();

users.get('/', listUsers);
users.get('/:id', getUser);
users.post('/', zValidator('json', createUserSchema), createUser);
users.put('/:id', zValidator('json', updateUserSchema), updateUser);
users.delete('/:id', deleteUser);

app.route('/api/users', users);

Middleware

Use Hono's built-in middleware where available

Create typed middleware for custom logic

Chain middleware for composability

import { cors } from 'hono/cors';
import { logger } from 'hono/logger';
import { jwt } from 'hono/jwt';

app.use('*', logger());
app.use('/api/*', cors());
app.use('/api/*', jwt({ secret: 'your-secret' }));

// Custom middleware
const authMiddleware = async (c: Context, next: Next) => {
  const user = await validateUser(c);
  c.set('user', user);
  await next();
};

Request Validation with Zod

Use @hono/zod-validator for request validation

Define schemas for all request inputs

Infer types from Zod schemas

import { z } from 'zod';
import { zValidator } from '@hono/zod-validator';

const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  role: z.enum(['user', 'admin']).default('user'),
});

type CreateUserInput = z.infer<typeof createUserSchema>;

app.post('/users', zValidator('json', createUserSchema), async (c) => {
  const data = c.req.valid('json');
  // data is typed as CreateUserInput
});

Context and Response Handling

Use typed context for better type safety

Use helper methods for responses: c.json(), c.text(), c.html()

Access environment bindings through context

app.get('/users/:id', async (c) => {
  const id = c.req.param('id');
  const db = c.env.DB;

  const user = await db.prepare('SELECT * FROM users WHERE id = ?')
    .bind(id)
    .first();

  if (!user) {
    return c.json({ error: 'User not found' }, 404);
  }

  return c.json(user);
});

Error Handling

Use Hono's HTTPException for expected errors

Create global error handler middleware

Return consistent error responses

import { HTTPException } from 'hono/http-exception';

// Throwing errors
if (!user) {
  throw new HTTPException(404, { message: 'User not found' });
}

// Global error handler
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json({ error: err.message }, err.status);
  }
  console.error(err);
  return c.json({ error: 'Internal Server Error' }, 500);
});

Cloudflare Workers Integration

Use Workers KV for key-value storage

Use D1 for SQL databases

Use R2 for object storage

Use Durable Objects for stateful applications

// D1 Database
const result = await c.env.DB.prepare('SELECT * FROM users').all();

// KV Storage
await c.env.KV.put('key', 'value');
const value = await c.env.KV.get('key');

// R2 Storage
await c.env.BUCKET.put('file.txt', content);

Testing

Use Hono's test client for integration tests

Use Vitest or Jest as test runner

Test handlers and middleware separately

import { testClient } from 'hono/testing';
import { describe, it, expect } from 'vitest';

describe('User API', () => {
  const client = testClient(app);

  it('should list users', async () => {
    const res = await client.api.users.$get();
    expect(res.status).toBe(200);
    const data = await res.json();
    expect(Array.isArray(data)).toBe(true);
  });
});

Performance

Hono is ultrafast with minimal overhead

Use streaming responses for large data

Leverage edge caching with Cache API

Use hono/tiny preset for minimal bundle size

Security

Use hono/secure-headers middleware

Implement rate limiting

Validate all inputs with Zod

Use JWT for authentication

Enable CORS appropriately

Multi-Runtime Support

Hono runs on multiple runtimes. Configure appropriately:

// Cloudflare Workers
export default app;

// Node.js
import { serve } from '@hono/node-server';
serve(app);

// Bun
export default app;

// Deno
Deno.serve(app.fetch);