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;

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-typescript

安装