Building Type-Safe APIs with Hono and TypeScript: RPC, Validation, and End-to-End Types

Type safety on an API boundary has two failure modes. The first is obvious: no types at all, runtime errors surfaced by monitoring. The second is subtle: types that exist but do not flow. You have @types/express, you write typed route handlers, you hand-roll z.object() in every handler, and you maintain a separate OpenAPI spec that gets out of date within two sprints. The type annotations give you a false sense of correctness. The spec diverges. A frontend engineer calls a field that was renamed three months ago and finds out at 11 PM.

Hono solves this differently. The types are not annotations bolted onto an existing framework; they are derived structurally from the route definitions. The RPC client does not consume a schema file or generated code: it imports the type of your router and infers every path, parameter, request body, and response shape from it. When you rename a field in a Zod schema, the TypeScript compiler tells every client call site that uses the old name.

This article goes deep on the mechanics: how the RPC inference actually works, how Zod validation integrates into the type system, how to compose middleware without losing type information, and where Hono’s approach wins and loses against tRPC in a direct code-level comparison.

How Hono Accumulates Route Types

The core mechanism that makes RPC inference possible is Hono’s use of TypeScript generics to accumulate route types as you chain route definitions. This is not magic. It is a deliberate design choice that constrains how you write routes.

When you call app.get('/users', handler) on a plain Hono instance, that call mutates the app in place and returns this. The type of this is the full generic type with the new route appended. If you chain calls, TypeScript can track each route as part of the accumulated type. If you assign the result of each app.get() call to a new variable (or call them independently), the accumulation breaks.

Here is what the accumulation looks like internally. You do not need to understand the implementation, but the model clarifies why chaining is required:

// Hono's generic type tracks routes as a tuple
type RouteList = [
  { method: 'get'; path: '/users'; output: { users: User[] } },
  { method: 'post'; path: '/users'; input: CreateUser; output: User },
  // ... each route added via chaining
]

// The RPC client maps this tuple to a typed call interface:
// client.users.$get() => Promise<Response<{ users: User[] }>>
// client.users.$post({ json: CreateUser }) => Promise<Response<User>>

The practical implication: routes must be chained on the same Hono instance or sub-router for the RPC type to capture them.

// This works - chained calls accumulate the type
export const usersRouter = new Hono()
  .get('/', listUsers)
  .post('/', createUser)
  .get('/:id', getUser)
  .patch('/:id', updateUser)
  .delete('/:id', deleteUser)

// This does NOT work for RPC - types are not captured
const usersRouter = new Hono()
usersRouter.get('/', listUsers)   // type lost here
usersRouter.post('/', createUser) // type lost here

export type UsersRouterType = typeof usersRouter // misses the routes

This constraint is the most common source of confusion when migrating from Express to Hono. In Express, the pattern of calling router.get() imperatively is idiomatic. In Hono, you need to switch to the fluent chain pattern for RPC to work.

Zod Validation: More Than Schema Checking

The @hono/zod-validator middleware does three things simultaneously: validates the input against the schema, parses and transforms the result, and makes the parsed output available on the context with full type inference. The type is derived from the Zod schema, including any transforms.

Install the dependencies:

npm install zod @hono/zod-validator

The basic pattern:

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

const createProjectSchema = z.object({
  name: z.string().min(1).max(120).trim(),
  slug: z
    .string()
    .min(1)
    .max(60)
    .regex(/^[a-z0-9-]+$/, 'Slug must be lowercase alphanumeric with hyphens')
    .transform((s) => s.toLowerCase()),
  visibility: z.enum(['public', 'private', 'internal']).default('private'),
  tags: z.array(z.string().max(50)).max(10).default([]),
  metadata: z
    .record(z.string(), z.string())
    .optional()
    .transform((m) => m ?? {}),
})

// The inferred type after transforms:
// {
//   name: string          (trimmed)
//   slug: string          (lowercased)
//   visibility: 'public' | 'private' | 'internal'
//   tags: string[]        (defaulted)
//   metadata: Record<string, string>  (defaulted from undefined)
// }

const app = new Hono()

app.post(
  '/projects',
  zValidator('json', createProjectSchema),
  async (c) => {
    const data = c.req.valid('json')
    // data.slug is already lowercased by the transform
    // data.metadata is Record<string, string>, not undefined
    // No runtime casting needed
    const project = await db.projects.create(data)
    return c.json(project, 201)
  }
)

The key detail: c.req.valid('json') returns the output type of the Zod schema, which includes transforms. This is not just structural validation; the value you get back is the transformed value. You do not need parseInt(), .toLowerCase(), or null-coalescing for optional fields with defaults scattered through your handlers.

Validating Multiple Sources

You can stack validators for different parts of the request:

const listProjectsQuery = z.object({
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  visibility: z.enum(['public', 'private', 'internal']).optional(),
  search: z.string().max(200).trim().optional(),
  sortBy: z.enum(['name', 'createdAt', 'updatedAt']).default('createdAt'),
  sortOrder: z.enum(['asc', 'desc']).default('desc'),
})

const projectParamSchema = z.object({
  orgId: z.string().uuid(),
})

const app = new Hono()

app.get(
  '/orgs/:orgId/projects',
  zValidator('param', projectParamSchema),
  zValidator('query', listProjectsQuery),
  async (c) => {
    const { orgId } = c.req.valid('param')  // typed as { orgId: string }
    const query = c.req.valid('query')       // all query fields typed and coerced

    const offset = (query.page - 1) * query.limit

    const projects = await db.projects.list({
      orgId,
      offset,
      limit: query.limit,
      visibility: query.visibility,
      search: query.search,
      sortBy: query.sortBy,
      sortOrder: query.sortOrder,
    })

    return c.json({
      projects,
      pagination: {
        page: query.page,
        limit: query.limit,
        total: projects.totalCount,
      },
    })
  }
)

Without z.coerce.number() on the query parameters, arithmetic on page and limit produces NaN silently. This is not a Hono problem; it is the nature of HTTP query parameters being strings. Coercion at the validation boundary means your handler code never has to deal with it.

Custom Validation Error Responses

The default validation error response from @hono/zod-validator is a 400 with the raw Zod error object. For a production API, you want a consistent, client-parseable error format:

import type { ValidationTargets } from 'hono'
import type { ZodSchema } from 'zod'

function validate<T extends ZodSchema>(
  target: keyof ValidationTargets,
  schema: T
) {
  return zValidator(target, schema, (result, c) => {
    if (!result.success) {
      return c.json(
        {
          error: 'VALIDATION_ERROR',
          target,
          issues: result.error.issues.map((issue) => ({
            path: issue.path.join('.'),
            code: issue.code,
            message: issue.message,
            ...(issue.code === 'invalid_enum_value' && {
              received: issue.received,
              options: issue.options,
            }),
          })),
        },
        400
      )
    }
  })
}

// Usage is identical to zValidator
app.post('/projects', validate('json', createProjectSchema), async (c) => {
  const data = c.req.valid('json')
  // ...
})

This wrapper preserves full type inference while giving you control over the error shape. The client gets a predictable { error: 'VALIDATION_ERROR', issues: [...] } structure it can switch on.

Middleware Composition and the Variables Type

Hono middleware participates in the type system through the Variables generic. Without declaring what your middleware sets on the context, c.get() returns unknown. With it, return types are precise and call sites that ask for undeclared variables are type errors.

The pattern for reusable typed middleware uses createMiddleware from hono/factory:

import { createMiddleware } from 'hono/factory'
import { HTTPException } from 'hono/http-exception'
import { verify } from 'hono/jwt'

type AuthUser = {
  id: string
  email: string
  orgId: string
  role: 'owner' | 'admin' | 'member' | 'viewer'
  permissions: string[]
}

type AuthVariables = {
  user: AuthUser
}

// createMiddleware carries the Variables type through
const authenticate = createMiddleware<{
  Bindings: { JWT_SECRET: string }
  Variables: AuthVariables
}>(async (c, next) => {
  const header = c.req.header('Authorization')
  if (!header?.startsWith('Bearer ')) {
    throw new HTTPException(401, { message: 'Authorization header required' })
  }

  const token = header.slice(7)
  let payload: Record<string, unknown>

  try {
    payload = await verify(token, c.env.JWT_SECRET)
  } catch {
    throw new HTTPException(401, { message: 'Token invalid or expired' })
  }

  c.set('user', {
    id: payload.sub as string,
    email: payload.email as string,
    orgId: payload.orgId as string,
    role: payload.role as AuthUser['role'],
    permissions: payload.permissions as string[],
  })

  await next()
})

// Role guard - composes with authenticate
const requirePermission = (permission: string) =>
  createMiddleware<{ Variables: AuthVariables }>(async (c, next) => {
    const user = c.get('user')
    if (!user.permissions.includes(permission)) {
      throw new HTTPException(403, {
        message: `Permission required: ${permission}`,
      })
    }
    await next()
  })

When you apply these middleware to routes, the Variables type flows through:

type Bindings = { JWT_SECRET: string; DB: D1Database }
type Variables = AuthVariables

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

app.use('/api/*', authenticate)

app.delete(
  '/api/projects/:id',
  requirePermission('projects:delete'),
  async (c) => {
    const user = c.get('user') // typed as AuthUser, not unknown
    const projectId = c.req.param('id')

    await db.projects.delete(projectId, user.orgId)
    return c.body(null, 204)
  }
)

The user variable is fully typed at the handler call site. If you rename a field on AuthUser, every handler that accesses that field through c.get('user') becomes a compile error.

The RPC Client in Practice

The RPC client is where Hono’s type system pays off most clearly. The setup requires that routes be exported as typed Hono instances:

// src/routes/projects.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

// Define schemas in the routes file so they can be shared
export const projectSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  slug: z.string(),
  visibility: z.enum(['public', 'private', 'internal']),
  orgId: z.string().uuid(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
})

const createSchema = projectSchema.omit({ id: true, createdAt: true, updatedAt: true })
const updateSchema = createSchema.partial().omit({ orgId: true })

export const projectsRouter = new Hono<{
  Bindings: { DB: D1Database }
  Variables: AuthVariables
}>()
  .get('/', async (c) => {
    const projects = await db.projects.list({ orgId: c.get('user').orgId })
    return c.json({ projects })
  })
  .get('/:id', async (c) => {
    const id = c.req.param('id')
    const orgId = c.get('user').orgId
    const project = await db.projects.findById(id, orgId)
    if (!project) throw new HTTPException(404, { message: 'Project not found' })
    return c.json(project)
  })
  .post('/', zValidator('json', createSchema), async (c) => {
    const data = c.req.valid('json')
    const project = await db.projects.create({
      ...data,
      orgId: c.get('user').orgId,
    })
    return c.json(project, 201)
  })
  .patch('/:id', zValidator('json', updateSchema), async (c) => {
    const id = c.req.param('id')
    const data = c.req.valid('json')
    const orgId = c.get('user').orgId
    const project = await db.projects.update(id, orgId, data)
    if (!project) throw new HTTPException(404, { message: 'Project not found' })
    return c.json(project)
  })
  .delete('/:id', async (c) => {
    const id = c.req.param('id')
    await db.projects.delete(id, c.get('user').orgId)
    return c.body(null, 204)
  })

// Export the router type for the RPC client
export type ProjectsRouterType = typeof projectsRouter

// src/index.ts
import { Hono } from 'hono'
import { projectsRouter } from './routes/projects'

const app = new Hono()
  .route('/api/projects', projectsRouter)

export type AppType = typeof app
export default app

On the client, the import is a type-only import. No server code is bundled:

// client/api.ts
import { hc } from 'hono/client'
import type { AppType } from '../src/index'

export const api = hc<AppType>('https://api.example.com', {
  headers: () => ({
    Authorization: `Bearer ${getAccessToken()}`,
  }),
})

// Usage with full type inference
async function fetchProjects() {
  const res = await api.api.projects.$get()
  if (!res.ok) throw new Error('Failed to fetch projects')
  const { projects } = await res.json()
  // projects: Array<{ id: string; name: string; slug: string; ... }>
  return projects
}

async function createProject(input: {
  name: string
  slug: string
  visibility: 'public' | 'private' | 'internal'
  orgId: string
}) {
  const res = await api.api.projects.$post({ json: input })
  // Passing an invalid visibility value here is a compile error
  // Omitting a required field is a compile error
  return res.json()
}

async function updateProject(id: string, name: string) {
  const res = await api.api.projects[':id'].$patch({
    param: { id },
    json: { name },
  })
  return res.json()
}

The headers option on hc() accepts a function that is called on each request, which is the right pattern for tokens that rotate. Do not pass a static token: it will be the token value at client initialization time, not the current token.

When the RPC Pattern Does Not Fit

The RPC client is the right choice when server and client are in the same codebase or can share a type package. It is the wrong choice for:

• Public APIs with external consumers who do not control their client code. They need an OpenAPI spec. Hono can generate one with @hono/zod-openapi, but you are then maintaining an OpenAPI API rather than an RPC API.
• APIs consumed by non-TypeScript clients. The RPC client is TypeScript-specific. A Python script hitting your Hono API does not benefit from it.
• Services with multiple independent frontend teams who cannot share the monorepo boundary. Publish the types as an npm package if needed, but that adds a release step that can lag behind the server.

Hono vs. tRPC: A Direct Comparison

Both Hono and tRPC provide end-to-end type safety without code generation. The difference is in what they optimize for.

tRPC optimizes for full-stack TypeScript applications where server and client are tightly coupled and the transport is not a concern. It uses a custom RPC protocol (HTTP POST with batching, subscriptions via WebSocket) and is designed to be used with React Query on the client.

Hono optimizes for standard HTTP APIs that happen to have a typed client. The transport is plain HTTP. Routes look like REST routes. Any HTTP client can call a Hono API; the typed RPC client is one option, not the only one.

Here is the same user listing endpoint implemented in both:

// tRPC version
import { initTRPC } from '@trpc/server'
import { z } from 'zod'

const t = initTRPC.context<{ userId: string; orgId: string }>().create()

export const appRouter = t.router({
  projects: t.router({
    list: t.procedure.query(async ({ ctx }) => {
      return db.projects.list({ orgId: ctx.orgId })
    }),
    create: t.procedure
      .input(
        z.object({
          name: z.string().min(1).max(120),
          slug: z.string().regex(/^[a-z0-9-]+$/),
          visibility: z.enum(['public', 'private', 'internal']),
        })
      )
      .mutation(async ({ input, ctx }) => {
        return db.projects.create({ ...input, orgId: ctx.orgId })
      }),
  }),
})

// tRPC client
const trpc = createTRPCReact<AppRouter>()
const projects = trpc.projects.list.useQuery()
const create = trpc.projects.create.useMutation()

// Hono RPC version
export const projectsRouter = new Hono<{ Variables: AuthVariables }>()
  .get('/', async (c) => {
    const projects = await db.projects.list({ orgId: c.get('user').orgId })
    return c.json({ projects })
  })
  .post('/', zValidator('json', createSchema), async (c) => {
    const data = c.req.valid('json')
    return c.json(
      await db.projects.create({ ...data, orgId: c.get('user').orgId }),
      201
    )
  })

// Hono client (plain async/await, not React-specific)
const res = await api.api.projects.$get()
const { projects } = await res.json()

const created = await api.api.projects.$post({ json: createInput })

The structural differences:

Dimension	tRPC	Hono RPC
Transport	Custom POST + batching	Standard HTTP (GET, POST, PATCH, DELETE)
Client model	React Query hooks built-in	Plain fetch wrapper, any React integration
URL structure	/trpc/projects.list	/api/projects
External consumers	Cannot use typed client	Can call with any HTTP client
Streaming	WebSocket subscriptions built-in	SSE via streamSSE() helper
Middleware model	Context-based, set up at router init	(c, next) with typed Variables
File uploads	Awkward with tRPC’s POST model	Natural with multipart form data
Edge runtimes	Depends on adapter	Native with Workers adapter
REST semantics	Absent by design	First-class

Neither is better in the abstract. tRPC is faster to set up for a Next.js full-stack app that will never have external consumers. Hono is the better default when the API needs to be called by mobile apps, third-party integrations, or non-React frontends in addition to the primary web client.

Structured Error Handling

Hono’s onError handler is global. The pattern that works for typed error responses separates three categories: validation errors (from zValidator), HTTP exceptions (from HTTPException), and unexpected errors:

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

// Typed error codes - clients can switch on these
type ErrorCode =
  | 'VALIDATION_ERROR'
  | 'NOT_FOUND'
  | 'FORBIDDEN'
  | 'UNAUTHORIZED'
  | 'CONFLICT'
  | 'INTERNAL_ERROR'

type ApiError = {
  error: ErrorCode
  message: string
  details?: unknown
}

app.onError((err, c): Response => {
  if (err instanceof HTTPException) {
    const code = httpStatusToCode(err.status)
    return c.json<ApiError>(
      { error: code, message: err.message },
      err.status as 400 | 401 | 403 | 404 | 409 | 500
    )
  }

  // Log unexpected errors with context
  console.error(
    JSON.stringify({
      error: err.message,
      stack: err.stack,
      path: c.req.path,
      method: c.req.method,
      // On Workers, this includes the CF-Ray ID for tracing
      cfRay: c.req.header('CF-Ray'),
    })
  )

  return c.json<ApiError>(
    { error: 'INTERNAL_ERROR', message: 'An unexpected error occurred' },
    500
  )
})

function httpStatusToCode(status: number): ErrorCode {
  const map: Record<number, ErrorCode> = {
    400: 'VALIDATION_ERROR',
    401: 'UNAUTHORIZED',
    403: 'FORBIDDEN',
    404: 'NOT_FOUND',
    409: 'CONFLICT',
  }
  return map[status] ?? 'INTERNAL_ERROR'
}

One pattern worth adding on top of this: a typed throwApiError helper that keeps error creation consistent and avoids scattered new HTTPException() calls with inconsistent messages:

const errors = {
  notFound: (resource: string, id: string) =>
    new HTTPException(404, { message: `${resource} not found: ${id}` }),

  forbidden: (action: string) =>
    new HTTPException(403, { message: `Forbidden: ${action}` }),

  conflict: (field: string, value: string) =>
    new HTTPException(409, {
      message: `Conflict: ${field} '${value}' already exists`,
    }),

  unauthorized: () =>
    new HTTPException(401, { message: 'Authentication required' }),
}

// Usage in handlers
app.get('/projects/:id', async (c) => {
  const id = c.req.param('id')
  const project = await db.projects.findById(id)
  if (!project) throw errors.notFound('project', id)
  return c.json(project)
})

Testing with app.request()

Hono’s built-in app.request() method creates a real Request and processes it through the full middleware chain without starting an HTTP server. For unit and integration tests, this is sufficient:

import { describe, it, expect, vi, beforeEach } from 'vitest'
import app from '../src/index'

// Mock the database layer, not the framework
vi.mock('../src/db', () => ({
  db: {
    projects: {
      list: vi.fn(),
      create: vi.fn(),
      findById: vi.fn(),
    },
  },
}))

// Helper to create authenticated requests
function authRequest(
  path: string,
  options: RequestInit = {},
  user = { id: 'user-1', orgId: 'org-1', role: 'admin' }
): Promise<Response> {
  const token = createTestJWT(user)
  return app.request(path, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
  })
}

describe('POST /api/projects', () => {
  it('creates a project with valid input', async () => {
    vi.mocked(db.projects.create).mockResolvedValue({
      id: 'proj-1',
      name: 'My Project',
      slug: 'my-project',
      visibility: 'private',
      orgId: 'org-1',
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    })

    const res = await authRequest('/api/projects', {
      method: 'POST',
      body: JSON.stringify({
        name: 'My Project',
        slug: 'my-project',
        visibility: 'private',
        orgId: 'org-1',
      }),
    })

    expect(res.status).toBe(201)
    const project = await res.json()
    expect(project.slug).toBe('my-project')
  })

  it('rejects an invalid slug format', async () => {
    const res = await authRequest('/api/projects', {
      method: 'POST',
      body: JSON.stringify({
        name: 'My Project',
        slug: 'My Project!', // invalid: uppercase, spaces, special chars
        visibility: 'private',
        orgId: 'org-1',
      }),
    })

    expect(res.status).toBe(400)
    const error = await res.json()
    expect(error.issues.some((i: { path: string }) => i.path === 'slug')).toBe(true)
  })

  it('returns 401 without an authorization header', async () => {
    const res = await app.request('/api/projects', { method: 'POST' })
    expect(res.status).toBe(401)
  })
})

The test mocks the database layer at the boundary it controls (the db module), not the framework internals. Validation, authentication middleware, and error handling all run as they do in production.

For Workers-specific tests that need real bindings (D1Database, KVNamespace), use @cloudflare/vitest-pool-workers. It boots a Miniflare Workers runtime for the test suite and binds the same resources defined in wrangler.toml.

Production Considerations

Bundle size on Workers. Hono’s core is approximately 14 KB minified and gzipped. Zod adds approximately 12 KB. The total for a typical Hono API with validation is 30-40 KB, well within Workers’ 1 MB compressed script size limit. Do not import Zod schemas from a shared package that also exports server-only code: Workers have no tree-shaking at the binding level, and importing an fs-based module in a Worker will fail at runtime, not build time.

D1 latency and query patterns. D1 uses the same regional placement as your Worker. A wrangler.toml without an explicit [[d1_databases]] ... region sends requests to Cloudflare’s default region for your account, which may not be close to your primary users. Check the D1 dashboard metrics for per-region latency after deployment. For APIs with strict p95 requirements, measure before assuming D1 is fast enough.

Request body streaming. Hono reads the full request body before running validators. For JSON APIs, this is fine. For file uploads, do not use zValidator('json', ...) on a multipart/form-data request: read it with c.req.parseBody() instead and validate individual fields manually.

Type narrowing on response.ok. The RPC client’s response.json() return type is derived from the route’s c.json() calls. But HTTP can always return an error. Before calling .json(), check response.ok. The type system does not force this check; you need to build the discipline into your client layer:

async function safeGet<T>(res: Response): Promise<T> {
  if (!res.ok) {
    const error = await res.json().catch(() => ({ error: 'Unknown error' }))
    throw new ApiError(res.status, error)
  }
  return res.json() as Promise<T>
}

What Hono’s Type System Does Not Cover

Hono gives you type safety on the path from request input to response output. It does not give you:

• Response body narrowing on error status codes. c.json(data, 200) and c.json(error, 404) both contribute to the route’s inferred response type as a union. The client gets a union type and must narrow it manually.
• Database return type verification. If your Drizzle or Prisma query returns a shape that does not match your Zod schema, and you pass it directly to c.json(), TypeScript will not catch it unless you run schema.parse(dbResult) explicitly.
• Cross-route consistency. If /projects/:id returns a Project with an owner field and /orgs/:id/projects returns projects without the owner field, the types are correct for each route but inconsistent across the API. This is a design problem, not a type system problem.

Hono’s type safety is real and useful. It is not a substitute for data validation at the database boundary or for consistent API design.

Closing Thoughts

The argument for Hono is not that it is the fastest framework or has the most middleware. It is that the type system is structural rather than decorative. The contract between your server and your clients is encoded in TypeScript and enforced by the compiler, not maintained in a separate spec file that drifts.

The RPC client is the feature that makes this concrete. When a senior engineer refactors a response schema, the compiler catches every broken call site across the codebase immediately. When a new field is added to a request schema as required, every caller that does not supply it becomes a build error before it becomes a production incident.

The constraints are real: chained route definitions are required for RPC type accumulation, and you need a shared type boundary between server and client. Neither constraint is unreasonable for a new project. They are worth understanding explicitly before you start so you architect around them rather than discovering them mid-build.