Someone adds a field to an interface, and the schema never gets updated. The docs stay stale until a client files a bug. There's no compiler error or failing test. The three sources of truth just drift apart.

In this tutorial, you'll learn how to collapse those three concerns into one definition using Hono and Zod. You'll build the same patterns I use in production, including in ClipForge, an open-source video processing toolkit I built and maintain. They help validation, types, and docs stay in sync by design.

By the end of this article, you should know how to:

• Define one Zod schema that handles runtime validation, TypeScript types, and OpenAPI docs

• Structure routes so the contract and the handler stay separated

• Keep database schemas and HTTP schemas as two deliberate layers

• Return one consistent error shape from every failure path

• Carry those same patterns from a small Tasks API into a real multi-service system

Prerequisites

To get the most out of this article, you'll need to know:

• JavaScript and basic TypeScript

• How REST APIs work (routes, request bodies, status codes)

• A little Node.js (installing packages, running scripts)

You don't need prior experience with Hono, Zod, or Drizzle.

Table of Contents

• Prerequisites

• 1. The Drift Problem

• 2. What Is Hono?

• 3. What Is Zod?

• 4. One Schema, Three Jobs

• 5. How to Set Up the Project

• 6. How to Define Your API Schemas

• 7. How to Separate Database Schemas from API Schemas

• 8. How to Define Routes as Contracts

• 9. How to Keep Handlers Thin

• 10. How to Return One Error Shape Everywhere

• 11. How to Generate Docs That Can't Drift

• 12. How to Make the App Production-Ready

• 13. How These Patterns Scale in a Production App

• Conclusion

1. The Drift Problem

Most TypeScript APIs end up maintaining three separate descriptions of the same data:

1. Runtime validation checks that run when a request arrives

2. TypeScript types shapes the compiler understands at build time

3. API documentation, the contract you show to consumers

Each one lives in a different file and updates on a different schedule. And none of them can see the others.

Figure 1: Three descriptions of the same data, maintained separately and often out of sync.

Hand-written interfaces disappear at runtime. Joi or Yup schemas validate data but don't give you types for free. OpenAPI files are usually edited by hand, if they're edited at all.

The fix is not "be more careful." The fix is one definition that produces all three outputs.

Figure 2: One schema definition produces three outputs.

That is what Hono and Zod give you when you use them together through @hono/zod-openapi.

2. What Is Hono?

Hono is a small, fast web framework built on Web Standard APIs, the same Request and Response primitives that run in Node.js, Deno, Bun, and Cloudflare Workers.

Compared with Express, that difference matters:

Hono's core is about 14kb. On Node it's roughly 5–7× faster than Express for the same workload. On Bun or Cloudflare Workers, the gap widens further because those runtimes are optimized for web standards.

For most CRUD APIs, your database is still the bottleneck. But at high concurrency, or on edge runtimes where cold starts matter, the framework gap is real.

More importantly for this tutorial: Hono's OpenAPI integration lets your route definition be the documentation.

3. What Is Zod?

Zod is a TypeScript-first schema validation library. You describe the shape of your data once. Zod then:

1. Validates that shape at runtime

2. Infers the TypeScript type with z.infer

3. Feeds OpenAPI docs when you attach .openapi() metadata

With Joi or Yup, you usually validate at runtime and then hand-write a matching interface. That's two definitions again. Zod removes the second one.

import { z } from 'zod';

const createTaskSchema = z.object({
  title: z.string().min(1).max(120),
  status: z.enum(['todo', 'in_progress', 'done']).default('todo'),
});

type CreateTaskInput = z.infer<typeof createTaskSchema>;
// { title: string; status?: "todo" | "in_progress" | "done" }

Change the schema, and every callsite that depends on CreateTaskInput updates with it. TypeScript will tell you what broke.

4. One Schema, Three Jobs

Here's the mental model for the rest of the article:

Figure 3: taskSchema is the single source of truth for validation, types, and docs.

1. Runtime validation: bad data is rejected before it reaches your handler, with structured field errors instead of a stack trace

2. TypeScript types: z.infer<typeof schema> is derived from the schema, not maintained beside it

3. OpenAPI docs: .openapi('Name') registers the schema in the generated spec, so /reference stays current

One definition with three outputs. Nothing to keep in sync by hand.

5. How to Set Up the Project

We'll use the companion demo from api-conf-demo. It's a small Tasks API that shows the patterns cleanly. Later, we'll look at how the same ideas show up in ClipForge at a larger scale.

Clone the repo and install dependencies:

git clone https://github.com/otutukingsley/api-conf-demo.git
cd api-conf-demo
npm install

Start the server:

npm run dev

You should see the API on http://localhost:8080, with interactive docs at /reference.

The important folders look like this:

src/
├── db/schema/          # Persistence layer (Drizzle tables)
├── lib/schemas/        # HTTP contract layer (Zod + OpenAPI)
├── lib/errors/         # One error envelope for every failure
├── routes/tasks/       # Route contracts + handlers
├── services/           # Business logic and DB access
├── app.ts              # Middleware, routers, OpenAPI wiring
└── env.ts              # Zod-validated environment config

This is still MVC. The tooling is just better:

Figure 4: Still MVC. Routes and handlers as the controller, schemas as the contract, and services as the model.

• Model services its own business logic and database access

• View / contract schemas define what data looks like at the DB and HTTP boundaries

• Controller routes declare the contract, handlers fulfill it

A request through the demo API looks like this:

Figure 5: Request flow through the demo API, including the validation failure path.

In that diagram, a request flows through the Client, Middleware, Route contract, Handler, Service, and DB. Middleware handles logging and CORS. The route contract validates the body with Zod.

If validation fails, the client gets a 422 ApiError and the handler never runs. If it passes, the handler gets a typed CreateTaskInput, calls TaskService.create(), the service inserts and parses the row, and the client gets 201 with the Task JSON.

6. How to Define Your API Schemas

Start with the HTTP contract in src/lib/schemas/task.ts:

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

export const taskStatusSchema = z
  .enum(['todo', 'in_progress', 'done'])
  .openapi('TaskStatus');

export const taskSchema = z
  .object({
    id: z.string().uuid().openapi({
      example: '8e2c9f0a-2222-4a5a-9c3e-1a2b3c4d5e6f',
    }),
    title: z.string().min(1).max(120).openapi({
      example: 'Write the talk abstract',
    }),
    description: z.string().max(2000).nullable().openapi({
      example: 'Cover Hono + Zod patterns',
    }),
    status: taskStatusSchema.default('todo'),
    dueDate: z.string().date().nullable().openapi({
      example: '2026-07-15',
    }),
    createdAt: z.string().openapi({ example: '2026-06-28 10:15:00' }),
    updatedAt: z.string().openapi({ example: '2026-06-28 10:15:00' }),
  })
  .openapi('Task');

export type Task = z.infer<typeof taskSchema>;

That one object is now the runtime validator, TypeScript type, and an OpenAPI component named Task.

Request schemas should derive from the same base instead of being redeclared:

export const createTaskSchema = taskSchema
  .pick({ title: true, description: true, status: true, dueDate: true })
  .partial({ description: true, status: true, dueDate: true })
  .openapi('CreateTask');

export const updateTaskSchema = createTaskSchema
  .partial()
  .openapi('UpdateTask');

export type CreateTaskInput = z.infer<typeof createTaskSchema>;
export type UpdateTaskInput = z.infer<typeof updateTaskSchema>;

CreateTask never includes id, because clients don't send one. UpdateTask makes every field optional, because a PATCH can touch any subset.

Figure 6: Request schemas derive from the same base resource schema.

We have three contracts with one source.

7. How to Separate Database Schemas from API Schemas

It's tempting to treat the database row and the API response as the same shape. In a tiny demo, they often look identical. In production, they diverge.

Keep them in separate files on purpose:

Figure 7: Keep database schemas and HTTP schemas as two deliberate layers.

Figure 7 has two panels connected by an arrow labeled "map" in the service.

Left pane src/db/schema/ (persistence):

• Starts from a Drizzle table definition

• That table drives SQL migrations

• It also produces drizzle-zod schemas for parsing rows

• And row insert/select types for TypeScript at the database boundary

Right panel src/lib/schemas/ (HTTP contract):

• Uses Zod + .openapi() as the public contract

• Defines request bodies / params clients may send

• Defines response bodies clients receive

• Registers OpenAPI components used by /doc and /reference

The arrow in the middle matters: the database shape isn't automatically the API shape. The service maps between them. That's why an internal column can exist on the left without becoming part of the HTTP contract on the right.

In short:

• src/db/schema/: what a row looks like in the database

• src/lib/schemas/: what the HTTP contract looks like

Here's the Drizzle table from the demo:

import { sql } from 'drizzle-orm';
import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
import { z } from 'zod';

export const taskStatusValues = ['todo', 'in_progress', 'done'] as const;

export const tasks = sqliteTable('tasks', {
  id: text('id').primaryKey(),
  title: text('title').notNull(),
  description: text('description'),
  status: text('status', { enum: taskStatusValues }).notNull().default('todo'),
  dueDate: text('due_date'),
  createdAt: text('created_at')
    .notNull()
    .default(sql`(current_timestamp)`),
  updatedAt: text('updated_at')
    .notNull()
    .default(sql`(current_timestamp)`),
});

export const selectTaskSchema = createSelectSchema(tasks, {
  status: z.enum(taskStatusValues),
});

export const insertTaskSchema = createInsertSchema(tasks, {
  id: () => z.string().uuid().optional(),
  title: () => z.string().min(1).max(120),
  description: () => z.string().max(2000).nullable().optional(),
  status: z.enum(taskStatusValues).optional(),
  dueDate: () => z.string().date().nullable().optional(),
});

One table definition gives you three outputs:

1. TypeScript types inferred from the columns

2. SQL migrations generated with drizzle-kit

3. Zod schemas via drizzle-zod

That's useful at the database boundary. It's not a replacement for your HTTP schemas.

The moment you add an internal archivedAt column, or a computed field the API returns that's not a column, the split pays for itself. Divergence becomes a normal change instead of a painful refactor.

Figure 8: The service decides what the client may see.

8. How to Define Routes as Contracts

In this architecture, a route doesn't "just handle a request." A route declares the contract: method, path, request schemas, and response schemas.

Figure 9: The route declares the contract. The handler fulfills it.

import { createRoute, z } from '@hono/zod-openapi';
import * as HttpStatusCodes from '@/lib/http-status-codes';
import { jsonContent } from '@/lib/openapi/json-content';
import { jsonApiErrorContent } from '@/lib/openapi/error-schema';
import {
  createTaskSchema,
  taskParamsSchema,
  taskSchema,
} from '@/lib/schemas/task';

export const createTask = createRoute({
  tags: ['Tasks'],
  method: 'post',
  path: '/tasks',
  summary: 'Create a task',
  request: {
    body: jsonContent(createTaskSchema, 'The task to create'),
  },
  responses: {
    [HttpStatusCodes.CREATED]: jsonContent(taskSchema, 'The created task'),
    [HttpStatusCodes.UNPROCESSABLE_ENTITY]:
      jsonApiErrorContent('Validation error'),
    [HttpStatusCodes.INTERNAL_SERVER_ERROR]: jsonApiErrorContent(
      'Internal server error',
    ),
  },
});

export const getTask = createRoute({
  tags: ['Tasks'],
  method: 'get',
  path: '/tasks/{id}',
  summary: 'Get a task by ID',
  request: {
    params: taskParamsSchema,
  },
  responses: {
    [HttpStatusCodes.OK]: jsonContent(taskSchema, 'The requested task'),
    [HttpStatusCodes.NOT_FOUND]: jsonApiErrorContent('Task not found'),
    [HttpStatusCodes.UNPROCESSABLE_ENTITY]:
      jsonApiErrorContent('Validation error'),
    [HttpStatusCodes.INTERNAL_SERVER_ERROR]: jsonApiErrorContent(
      'Internal server error',
    ),
  },
});

A small helper keeps response boilerplate readable:

export function jsonContent<T extends z.ZodTypeAny>(
  schema: T,
  description: string,
) {
  return {
    content: {
      'application/json': { schema },
    },
    description,
  };
}

Named status constants replace magic numbers. You use the same constants as object keys in the route and as switch cases in the handler. That makes status codes searchable and consistent.

9. How to Keep Handlers Thin

Once the route defines the contract, the handler only has to fulfill it.

export const getTask: AppRouteHandler<GetTaskRoute> = (c) => {
  try {
    const { id } = c.req.valid('param');
    return c.json(TaskService.get(id), HttpStatusCodes.OK);
  } catch (error) {
    const apiError = ApiError.parse(error);
    switch (apiError.statusCode) {
      case HttpStatusCodes.NOT_FOUND:
      case HttpStatusCodes.UNPROCESSABLE_ENTITY:
        return c.json(apiError.toResponseBody(), apiError.statusCode);
      default:
        return c.json(
          apiError.toResponseBody(),
          HttpStatusCodes.INTERNAL_SERVER_ERROR,
        );
    }
  }
};

export const createTask: AppRouteHandler<CreateTaskRoute> = (c) => {
  try {
    const body = c.req.valid('json');
    return c.json(TaskService.create(body), HttpStatusCodes.CREATED);
  } catch (error) {
    const apiError = ApiError.parse(error);
    switch (apiError.statusCode) {
      case HttpStatusCodes.UNPROCESSABLE_ENTITY:
        return c.json(apiError.toResponseBody(), apiError.statusCode);
      default:
        return c.json(
          apiError.toResponseBody(),
          HttpStatusCodes.INTERNAL_SERVER_ERROR,
        );
    }
  }
};

Notice what's not in the handler:

• No manual parsing of params or bodies

• No casting to any

• No business logic

c.req.valid('param') and c.req.valid('json') are already validated and typed. The service owns the database work:

get(id: string): Task {
  try {
    const row = db.select().from(tasks).where(eq(tasks.id, id)).get();
    if (!row) throw new NotFoundError(`Task ${id} not found`);
    return selectTaskSchema.parse(row);
  } catch (error) {
    throw ApiError.parse(error);
  }
},

The service wraps its body in one try/catch and normalizes every failure through ApiError.parse(). Zod errors, custom domain errors, and unexpected driver errors all become one typed shape.

10. How to Return One Error Shape Everywhere

Clients should never guess whether an error looks like { message }, { error }, or a raw stack trace.

In the demo, every failure becomes one envelope:

Figure 10: Every failure path becomes one predictable error shape.

The factory that creates routers bakes that behavior in with defaultHook:

export function createRouter() {
  return new OpenAPIHono({
    defaultHook: (result, c) => {
      if (!result.success) {
        const apiError = ApiError.parse(result.error);
        return c.json(apiError.toResponseBody(), apiError.statusCode);
      }
    },
  });
}

Every router goes through that factory. A bad UUID in a path param, a missing field in a POST body, or an invalid enum in a query string all produce the same response shape before the handler runs.

ApiError.parse() is the second half of the pattern:

public static parse(error: unknown): ApiError {
  if (error instanceof ApiError) return error;

  if (error instanceof ZodError) {
    return new ApiError('Validation error', {
      statusCode: 422,
      errors: error.flatten().fieldErrors,
    });
  }

  return new ApiError('Internal server error', { statusCode: 500 });
}

Handlers still use an explicit switch on status codes. That's intentional. Each route documents exactly which statuses it can return. A handler that should never emit 403 doesn't have 403 sitting in a shared helper's defaults.

The repetition is the point. Explicit beats clever here.

11. How to Generate Docs That Can't Drift

Because schemas are attached to route definitions, OpenAPI becomes a byproduct of the code instead of a separate chore.

Figure 11: Docs are generated from the same route definitions as the runtime code.

export function configureOpenAPI(app: OpenAPIHono) {
  app.doc('/doc', {
    openapi: '3.0.0',
    info: {
      title: 'Bulletproof Tasks API',
      version: '1.0.0',
    },
  });

  app.get(
    '/reference',
    apiReference({
      spec: { url: '/doc' },
      theme: 'kepler',
      layout: 'modern',
      pageTitle: 'Bulletproof Tasks API',
    }),
  );
}

• GET /doc returns the raw OpenAPI JSON

• GET /reference serves an interactive Scalar explorer

When you change a schema or a response code in the route file, the docs update with it. There's no second docs step to forget.

12. How to Make the App Production-Ready

Type safety at the request boundary isn't enough. Configuration and process lifecycle need the same discipline.

Validate Environment Variables at Boot

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z
    .enum(['development', 'test', 'production'])
    .default('development'),
  LOG_LEVEL: z
    .enum(['silent', 'debug', 'info', 'warn', 'error', 'fatal'])
    .default('info'),
  PORT: z.coerce.number().default(8080),
  DATABASE_URL: z.string().default('tasks.db'),
});

export const env = envSchema.parse(process.env);

If a required value is missing or malformed, the process exits immediately with a clear Zod error. That's much better than discovering undefined three requests into production.

Prefer Structured Logging

The demo uses Pino through hono-pino instead of a one-line console logger. In production you want JSON logs. In development you want something readable. One middleware can do both, and every request can carry a UUID.

Shut Down Cleanly

Docker and process managers send SIGTERM before they kill a process. Handle it. Close the HTTP server, then close the database handle, then exit. Without that, a SQLite file (or a Postgres connection pool) can be left in a dirty state.

Keep the App Runtime-Portable

Hono only depends on Web Standard APIs inside app. That means the same application object can run on Node:

import { serve } from '@hono/node-server';
import { app } from '@/app';

serve({ fetch: app.fetch, port: env.PORT });

Or on an edge runtime with almost nothing else:

import { app } from '@/app';

export default app;

That;s not a simplified example. That's the whole adapter.

13. How These Patterns Scale in a Production App

A Tasks API is a good teaching surface. Production systems are messier: you have uploads, background jobs, multiple packages, and longer-lived workflows.

ClipForge is a helpful example of a production app where those same ideas show up at scale. It's a self-hostable video processing toolkit built with Node.js, Hono, Zod, Drizzle, BullMQ, and Nuxt. You upload a video and get transcription, subtitles, summaries, chapter markers, and thumbnails.

The architecture looks like this:

apps/
├── api/        # Hono REST API
├── worker/     # BullMQ video processor
└── web/        # Nuxt frontend
packages/
├── shared/     # Zod schemas, constants, shared types
└── providers/  # OpenAI, Anthropic, Deepgram integrations

Figure 12: ClipForge keeps the same contract-first core across web, API, and worker packages.

A video job moves through stages like uploading, validating, extracting audio, and so on without inventing new response shapes along the way:

Figure 13: A video job moves through typed stages without inventing new response shapes.

The important part isn't the video pipeline. The important part is that the API still follows the same contract-first rules.

Shared Zod Schemas Across Packages

ClipForge keeps HTTP contracts in packages/shared, so the API, worker, and web app share one vocabulary:

export const processingFeatureSchema = z.enum([
  'transcription',
  'subtitles',
  'summary',
  'chapters',
  'thumbnails',
]);

export const videoUploadSchema = z.object({
  title: z.string().min(3).max(200),
  description: z.string().max(2000).optional(),
  features: z
    .array(processingFeatureSchema)
    .default([
      'transcription',
      'subtitles',
      'summary',
      'chapters',
      'thumbnails',
    ]),
  priority: z.enum(['low', 'normal', 'high']).default('normal'),
});

export const jobStatusSchema = z.object({
  jobId: z.string(),
  title: z.string().optional(),
  state: jobStateSchema,
  stage: jobStageSchema,
  progress: z.number().min(0).max(100),
  result: jobResultSchema.optional(),
  failedReason: z.string().optional(),
  createdAt: z.string(),
  updatedAt: z.string(),
});

When the worker finishes a stage, it doesn't invent a new response shape. It updates state against the same schemas the API returns to the client.

Routes Still Define the Contract

The upload route in ClipForge looks like the Tasks demo, just with multipart form data and rate limiting:

export const uploadVideo = createRoute({
  tags: ['videos'],
  method: 'post',
  path: '/videos/upload',
  middleware: [
    sessionMiddleware,
    apiKeysMiddleware,
    rateLimitMiddleware({
      windowMs: 60_000,
      max: 10,
      keyPrefix: 'ratelimit:upload',
    }),
  ] as const,
  request: {
    body: {
      content: {
        'multipart/form-data': {
          schema: z.object({
            file: z.instanceof(File),
            title: z.string().min(3).max(200),
            description: z.string().max(2000).optional(),
            features: z.string().optional(),
            priority: z.enum(['low', 'normal', 'high']).optional(),
          }),
        },
      },
    },
  },
  responses: {
    [HTTP_STATUS.ACCEPTED]: jsonContent(
      jobStatusSchema,
      'Video accepted for processing',
    ),
    [HTTP_STATUS.BAD_REQUEST]: jsonApiErrorContent('Invalid request'),
    [HTTP_STATUS.UNPROCESSABLE]: jsonApiErrorContent('Validation error'),
    [HTTP_STATUS.TOO_MANY_REQUESTS]: jsonApiErrorContent('Rate limit exceeded'),
  },
});

The handler validates input, writes a job row, enqueues BullMQ work, and returns 202 Accepted with a typed job status. The heavy lifting happens in the worker. The API stays a contract layer.

Figure 14: The API accepts the upload and returns a typed job status while the worker does the heavy lifting.

Figure 14 is a sequence diagram with five participants: Web UI, Hono API, BullMQ, Worker, and Postgres. It shows the async boundary between “accept the upload” and “finish processing.” Here's every step in the diagram:

1. The Web UI sends POST /videos/upload to the Hono API.

2. The Hono API runs Zod + middleware (validate input, session, rate limits, and related checks).

3. The Hono API performs insert job row in Postgres so the job exists before work starts.

4. The Hono API sends enqueue process-video to BullMQ.

5. The Hono API immediately returns 202 + jobStatusSchema to the Web UI. At this point the client has a typed job status, but transcription hasn't finished yet.

6. BullMQ later delivers process job to the Worker.

7. The Worker runs transcribe / analyze / thumbnails as background work.

8. The Worker writes update stage + result back to Postgres as stages complete.

9. The Web UI polls with GET /videos/jobs/{id} against the Hono API.

10. The Hono API reads the latest job from Postgres and returns jobStatusSchema agai the same response shape as step 5, now with updated stage, progress, and eventually result.

So the API stays a fast contract layer: accept, persist, enqueue, and respond. The worker owns the slow pipeline. The UI tracks progress by polling one share status schema.

Database Schemas Still Stay Separate

ClipForge stores jobs in Postgres with Drizzle:

export const jobs = pgTable('jobs', {
  id: varchar('id', { length: 36 }).primaryKey(),
  sessionId: varchar('session_id', { length: 36 }).notNull(),
  state: jobStateEnum('state').notNull().default('waiting'),
  stage: jobStageEnum('stage').notNull().default('uploading'),
  progress: integer('progress').notNull().default(0),
  title: varchar('title', { length: 200 }).notNull(),
  features: jsonb('features').$type<string[]>().notNull(),
  provider: varchar('provider', { length: 50 }).notNull().default('openai'),
  result: jsonb('result').$type<JobResult>(),
  failedReason: text('failed_reason'),
  createdAt: timestamp('created_at', { withTimezone: true })
    .notNull()
    .defaultNow(),
  updatedAt: timestamp('updated_at', { withTimezone: true })
    .notNull()
    .defaultNow(),
});

The table has persistence concerns like filePath and sessionId. The public jobStatusSchema doesn't have to expose all of them. That's the same DB-versus-API split from the Tasks demo, applied to a real workflow.

The Same Production Habits Still Apply

ClipForge validates environment variables with Zod on boot, configures OpenAPI and Scalar at /doc and /reference, normalizes failures through ApiError, and shuts down queues and Redis on SIGTERM.

The lesson is simple: if the small app is structured correctly, the large app doesn't need a different philosophy. It needs more packages, more middleware, and longer-running jobs on top of the same contract-first core.

Conclusion

Type-safe APIs aren't about adding more TypeScript. They're about removing duplicate sources of truth.

With Hono and Zod you can:

• validate requests at runtime

• infer types automatically

• generate OpenAPI docs from the same route definitions

• keep database schemas and HTTP schemas intentionally separate

• return one predictable error shape from every failure path

Start with the api-conf-demo if you want the smallest readable version of these patterns. Then look at ClipForge to see how the same ideas hold up when the API sits in front of uploads, queues, and multi-stage processing.

Once your route definition is the contract, your docs stop drifting, your handlers get thinner, and your clients get an API they can trust.

To resolve this issue in the past, you typically had to create a multitude of TypeScript interfaces by hand, using GraphQL Code Generator to generate the interface files, or hope that it all worked out. Well, there’s a better way to accomplish this now, without the need for code generation.

tRPC and Hono are two applications that are changing how we develop TypeScript-based applications throughout the entirety of the full-stack.

By the end of this tutorial, you’ll understand:

• Why traditional REST APIs fail at type safety

• How tRPC provides full end-to-end type inference between backend and frontend

• How Hono delivers type-safe APIs while staying REST-friendly

• When to choose tRPC vs Hono for your projects

• How these tools improve developer experience, team velocity, and reliability

If you’re building full-stack TypeScript applications and want fewer runtime bugs and faster iteration, this guide is for you.

Table of Contents

• Prerequisites

• The Problem with Traditional APIs

• What Makes tRPC Different?

• Hono: The Lightweight Challenger

• Why This Matters These Days

• Getting Started

• The Future is Type-Safe

Prerequisites

To follow along comfortably, you should have:

• Basic knowledge of TypeScript

• Familiarity with REST APIs and how frontend-backend communication works

• Some experience with Node.js and modern JavaScript frameworks

• A general understanding of frontend frameworks like React or Next.js (helpful, but not required)

You don’t need prior experience with tRPC, Hono, or GraphQL.

The Problem with Traditional APIs

You’ve probably written something like this a hundred times:

// Backend (Express)
app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  // Do stuff with user
  res.json({ id: 1, name, email });
});

// Frontend
const createUser = async (name: string, email: string) => {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, email })
  });
  return response.json(); 
};

The backend knows the shape of the data. But the frontend...it hopes it gets it right. You end up writing interfaces manually, like:

interface User {
  id: number;
  name: string;
  email: string;
}

If you change the backend tomorrow to return userId instead of id, TypeScript won't catch it. Your types and reality have diverged, and you won't know until runtime.

GraphQL tried to solve this with schemas and codegen, but honestly? Setting up GraphQL feels like assembling IKEA furniture without instructions. You need a schema, resolvers, code generation tools, and suddenly your "simple" API has a 30-minute setup process.

What Makes tRPC Different?

tRPC flips the script entirely. Instead of defining your API in a separate schema language, your TypeScript code is the schema. Here's the same API in tRPC:

// Backend (tRPC router)
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.create();

export const appRouter = t.router({
  createUser: t.procedure
    .input(z.object({
      name: z.string(),
      email: z.string().email(),
    }))
    .mutation(({ input }) => {
      // Do stuff with user
      return { id: 1, name: input.name, email: input.email };
    }),
});

export type AppRouter = typeof appRouter;

This is where it gets cool. On your frontend:

// Frontend - fully type-safe!
import { createTRPCClient } from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient<AppRouter>({
  url: 'http://localhost:3000/trpc',
});

// TypeScript knows EVERYTHING about this call
const user = await client.createUser.mutate({
  name: 'Alice',
  email: 'alice@example.com'
});

// user is automatically typed as { id: number; name: string; email: string; }

No code generation or build step, or GraphQL schema. Just pure TypeScript inference doing its thing. If you rename id to userId in your backend, your frontend will immediately show a TypeScript error. You'll catch it before you even save the file.

This is what we call end-to-end type safety, and it's honestly a great transition.

Hono: The Lightweight Challenger

While tRPC is amazing for full-stack TypeScript apps where you control both ends, Hono takes a slightly different approach. It's a lightweight web framework that gives you type safety while still being a traditional HTTP framework.

Here's the same example in Hono:

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

const app = new Hono();

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

app.post('/api/users', zValidator('json', userSchema), (c) => {
  const { name, email } = c.req.valid('json');
  return c.json({ id: 1, name, email });
});

export type AppType = typeof app;

On the frontend, you can use Hono’s RPC client:

import { hc } from 'hono/client';
import type { AppType } from './server';

const client = hc<AppType>('http://localhost:3000');

const response = await client.api.users.$post({
  json: { name: 'Bob', email: 'bob@example.com' }
});

const user = await response.json();
// user is fully typed!

Hono is incredibly fast (it runs on Cloudflare Workers, Deno, Bun, and Node.js), and it gives you that sweet type safety while still being a "regular" HTTP framework. You get RESTful routes, middleware, and all the familiar patterns – just with TypeScript powers.

Why This Matters These Days

You might think to yourself, “Okay, I know what you mean, but why should I care about it?” There’s a reason why these tools are being utilized more now than ever before.

Developer experience is essential

In 2026 and beyond, we’ll no longer accept long feedback loops. The ability to modify your backend code and see what might break on your frontend application without having to run the application will be fantastic for productivity. We’ll spend less time fixing bugs and more time creating new functionalities.

Smaller teams, better apps

With tRPC or Hono, one developer can create an entire full-stack application with type safety at a very fast pace because they don’t have to switch back and forth between REST documentation and TypeScript interfaces – all the data is flowing to and from their backend code directly to their frontend.

The end of “Works on my machine“

With type safety, errors are caught at compile time instead of at the time your end-user clicks on a button. This is especially impactful when working in larger teams, when the backend developers and front-end developers may not be in constant communication with one another.

Getting Started

Want to try this out? Here's the fastest way:

For tRPC:

npm create @trpc/next-app@latest

This scaffolds a Next.js app with tRPC already configured. Check out the official tRPC docs for more.

For Hono:

npm create hono@latest

Pick your runtime (Node.js, Cloudflare Workers, etc.), and you're off to the races. The Hono documentation is excellent and super approachable.

The Future is Type-Safe

Look, REST isn't going anywhere, and GraphQL has its place. But for full-stack TypeScript developers, tRPC and Hono represent something special: type safety without the ceremony. No code generation or no schema duplication, just TypeScript doing what it does best.

In the future, when you start a new project, give one of these a shot. Your future self – the one who's refactoring code at 2 AM – will thank you.

Happy coding!

The JavaScript ecosystem moves quickly. One minute, we're building monolithic Node.js servers. The next, it's all about serverless functions and running code at the edge on platforms like Cloudflare or Vercel. Staying current can feel like a full-time job.

Hono is built on top of Web Standards – the same Request and Response objects in your browser – which means your code is naturally portable across almost any JavaScript runtime.

This guide is a deep dive into this powerful little framework, designed to help you build real, production-ready applications. We’ll skip the quick "Hello, World!" and jump straight into the patterns and features you will actually use, with plenty of detailed code examples along the way.

Table of Contents

• What You Will Learn in This Guide

• Prerequisites for Following Along

• How to Set Up a Professional Hono Project

• How to Understand Hono's Core API

• The Context Object in Depth

• How to Use Advanced Features for Production Apps

• Deployment Guide for Hono

What You Will Learn in This Guide

By the end of this tutorial, you will be able to:

• Structure a Hono project for both development and production.

• Implement advanced routing patterns.

• Leverage the full power of the Context object to manage requests and pass data between middleware.

• Write complex custom middleware for authentication, logging, and error handling.

• Validate incoming data using the official Zod validator for robust APIs.

• Build a small, server-rendered application with JSX components.

• Deploy a Hono application to various modern hosting platforms.

Prerequisites for Following Along

This is an in-depth guide, but it assumes you have some foundational knowledge. Before you start, you should have:

• Node.js installed: Version 18 or higher is recommended.

• A code editor: Visual Studio Code is a great choice.

• Familiarity with TypeScript: You should understand basic types, functions, and async/await.

• Basic command-line knowledge: You should be comfortable running commands in your terminal.

How to Set Up a Professional Hono Project

You can get started with Hono using a single command. This will create a new project directory with a recommended structure and configuration files. When prompted, select the nodejs template and choose to install dependencies with your preferred package manager (for example, npm).

npm create hono@latest hono-production-app

The command will guide you through the setup:

> npx create-hono hono-production-app

create-hono version 0.19.2
✔ Using target directory … hono-production-app
✔ Which template do you want to use? nodejs
✔ Do you want to install project dependencies? Yes
✔ Which package manager do you want to use? npm
✔ Cloning the template
✔ Installing project dependencies
🎉 Copied project files
Get started with: cd hono-production-app

Now, navigate into your new directory: cd hono-production-app. Let's look at the files that were created:

• package.json: Defines your project's dependencies and scripts.

• tsconfig.json: The TypeScript configuration file.

• src/index.ts: The entry point of your application.

Now, you can run npm run dev to start your development server. Navigate to http://localhost:3000, and you will see "Hello Hono!".

How to Understand Hono's Core API

Hono's API is designed to be minimal, which makes it easy to learn – yet incredibly powerful.

How to Use Advanced Routing Techniques

You may already know app.get() and app.post() from Express, but Hono's router can do much more.

1. How to Route with Regular Expressions

You can constrain a URL parameter to match a specific regular expression. For example, to make sure an :id parameter only accepts numbers, you can do this:

// Only match routes like /users/123, not /users/abc
app.get('/users/:id{[0-9]+}', (c) => {
  const id = c.req.param('id')
  return c.text(`Fetching data for user ID: ${id}`)
})

2. How to Use Optional and Wildcard Routes

You can define routes that match multiple paths using wildcards (*) or handle optional parameters.

// This will match /files/image.png, /files/docs/report.pdf, and so on.
app.get('/files/*', (c) => {
  // c.req.path will contain the full matched path
  return c.text(`You are accessing the file at: ${c.req.path}`)
})

// The '?' makes the '/:format?' part of the URL optional
// This will match both /api/posts and /api/posts/json
app.get('/api/posts/:format?', (c) => {
  const format = c.req.param('format')
  if (format === 'json') {
    return c.json({ message: 'Here are the posts in JSON format.' })
  }
  return c.text('Here are the posts in plain text.')
})

3. How to Group Routes with app.route()

For larger applications, you should organize your routes into logical groups. The app.route() method is perfect for this. It allows you to create modular routers and mount them on a specific prefix.

Let's create a more complex API structure for a blog.

src/routes/posts.ts

import { Hono } from 'hono'

// Create a new router instance specifically for posts
const posts = new Hono()

posts.get('/', (c) => c.json({ posts: [] }))
posts.post('/', (c) => c.json({ message: 'Post created' }, 201))
posts.get('/:id', (c) => c.json({ post: { id: c.req.param('id') } }))

export default posts

src/routes/authors.ts

import { Hono } from 'hono'

const authors = new Hono()

authors.get('/', (c) => c.json({ authors: [] }))
authors.get('/:id', (c) => c.json({ author: { id: c.req.param('id') } }))

export default authors

src/index.ts

import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { appendTrailingSlash } from 'hono/trailing-slash';
import posts from './routes/posts.js'
import authors from './routes/authors.js'

const app = new Hono()

app.use(appendTrailingSlash());

app.route('/posts/', posts)
app.route('/authors/', authors)

app.get('/', (c) => {
  return c.text('Hello Hono!')
})

serve({
  fetch: app.fetch,
  port: 3000
}, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

This pattern keeps your main index.ts file clean and makes your application much easier to navigate and maintain.

The Context Object in Depth

The Context (c) is the heart of Hono. It's an object that gets passed to every middleware and route handler, containing all the information related to the current request. It's essentially a container for the request (c.req) methods for creating a response (c.json, c.html, c.text), as well as a special property for passing data between middleware (c.set and c.get).

While this covers its most common and useful properties, the full Context object contains more. For a comprehensive list of all available properties and methods, you can refer to the official Hono documentation.

Let's explore how you can use the context object to pass data between middleware and handlers, a crucial technique for things like authentication.

The c.set() and c.get() methods allow you to store and retrieve typed data within the context of a single request.

Replace src/index.ts with this example for authentication:

import { Hono } from 'hono'
import type { Context, Next } from 'hono'

// Define a type for the variables we will store in the context
type AppVariables = {
  user: {
    id: string
    name: string
    roles: string[]
  }
}

// Use a generic to tell our Hono app about the variables type
const app = new Hono<{ Variables: AppVariables }>()

// Middleware to "authenticate" a user from a header
const authMiddleware = async (c: Context, next: Next) => {
  const userId = c.req.header('X-User-ID')
  if (!userId) {
    return c.json({ error: 'Missing X-User-ID header' }, 401)
  }

  // In a real app, you would fetch this from a database
  const user = {
    id: userId,
    name: 'Jane Doe',
    roles: ['admin', 'editor'],
  }

  // Use c.set() to attach the user data to the context
  c.set('user', user)

  await next()
}

app.get('/admin/dashboard', authMiddleware, (c) => {
  // Use c.get() to retrieve the typed user data
  const user = c.get('user')

  if (!user.roles.includes('admin')) {
    return c.json({ error: 'Forbidden' }, 403)
  }

  return c.json({
    message: `Welcome to the admin dashboard, ${user.name}!`,
    userId: user.id,
  })
})

export default app

Let's break down the important parts of the code above.

• Typed context variables: We define a TypeScript type AppVariables and pass it as a generic to our Hono app new Hono<{ Variables: AppVariables }>(). This is a powerful feature that gives us full type-safety for our context variables, preventing typos and ensuring that the data we store and retrieve is exactly what we expect it to be.

• Custom middleware: The authMiddleware is a custom function that runs before our route handler. It inspects the incoming request's headers (c.req.header('X-User-ID')).

• Storing data: If a valid header is found, the middleware uses c.set('user', user) to store the user object on the context. This data is now available to any subsequent middleware or route handler for the same request.

• Retrieving data: The route handler app.get('/admin/dashboard', ...) then uses c.get('user') to retrieve the user object. Hono's type system ensures that c.get('user') returns a variable with the type { id: string; name: string; roles: string[]; }.

• Flow control: If the user is missing or doesn't have the "admin" role, the middleware or handler can immediately send an error response using c.json() and a status code, preventing the request from proceeding further.

Now, run npm run dev.

You can test with curl (add header):

curl -H "X-User-ID: 123" http://localhost:3000/admin/dashboard

This will return a welcome message.

Without the header:

curl http://localhost:3000/admin/dashboard

This will return a 401 error.

This demonstrates how to pass typed data securely and efficiently between middleware and route handlers.

How to Use Advanced Features for Production Apps

Now we're ready to tackle the features you'll use every day in production: advanced middleware, data validation, and building full-stack applications.

How to Use Advanced Middleware Patterns

Hono has a powerful set of built-in middleware, including JWT and caching. These are not separate libraries you have to install, but rather functions that come with the Hono package itself.

Step 1: Replace src/index.ts with this example for JWT and caching:

import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { jwt, sign } from 'hono/jwt'

const app = new Hono()
const SECRET = 'my-secret-key' // Use an environment variable in production!

// Create a simple in-memory cache store
const cacheStore = new Map();

// Custom caching middleware for Node.js
app.use('/api/public-data', async (c, next) => {
  const cacheKey = c.req.url;

  // Check if the response is in our cache
  if (cacheStore.has(cacheKey)) {
    const cachedItem = cacheStore.get(cacheKey);
    console.log('Serving from custom in-memory cache.');
    return new Response(cachedItem.body, { headers: cachedItem.headers });
  }

  // If not in cache, proceed to the route handler
  await next();

  // After the handler returns, clone and store the response
  if (c.res) {
    const newResponse = c.res.clone();
    const body = await newResponse.text();
    const headers = Object.fromEntries(newResponse.headers.entries());
    cacheStore.set(cacheKey, { body, headers });
    console.log('Storing response in custom in-memory cache.');
  }
});

// Login to get a JWT
app.post('/login', async (c) => {
  const { username } = await c.req.json()
  if (username === 'admin') {
    const payload = {
      sub: username,
      role: 'admin',
      exp: Math.floor(Date.now() / 1000) + 60 * 5, // 5 minutes expiration
    }
    const token = await sign(payload, SECRET)
    return c.json({ token })
  }
  return c.json({ error: 'Invalid credentials' }, 401)
})

// Protected route
app.get(
  '/api/protected',
  jwt({ secret: SECRET }),
  (c) => {
    const payload = c.get('jwtPayload')
    return c.json({ message: 'You have access!', payload })
  }
)

// Cached route
app.get(
  '/api/public-data',
  async (c) => {
    console.log('Executing handler with delay...');
    await new Promise(resolve => setTimeout(resolve, 1000)) // Simulate a delay
    return c.json({ data: 'This is some public data that rarely changes.' })
  }
)

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

The code above shows two different types of middleware in action.

First, JWT middleware (jwt) is a powerful way to secure your routes. When we call jwt({ secret: SECRET }), we're telling Hono to check for a valid JWT in the Authorization header of the incoming request. If a valid token is found, it decodes the payload and attaches it to the context, where we can retrieve it with c.get('jwtPayload'). If no token is found or if the token is invalid, the middleware automatically stops the request and returns a 401 Unauthorized error.

We also have Custom Cache Middleware which demonstrates the power of Hono's middleware system for in-memory caching. The middleware first checks an in-memory Map to see if a response for the current URL already exists. If it does, it immediately returns the cached response, preventing the route handler from ever being executed. If the response is not in the cache, it allows the request to continue to the handler. After the handler returns, the middleware intercepts the response and stores a copy in the cache before sending it back to the client. This is a robust and reliable pattern for Node.js environments.

Step 2: Run npm run dev.

Step 3: Test the login endpoint with curl:

First, let's test the login endpoint to get a JWT. Open a new terminal and run the following command. The command sends a POST request to the /login endpoint with username: "admin" in the request body.

curl -X POST http://localhost:3000/login -H "Content-Type: application/json" -d '{"username": "admin"}'

This will return a JSON object with a JWT. Copy this token for the next step.

Now, let's test the protected route. We'll use the token we just received in the Authorization header. Replace <your_jwt_token> with the token you copied.

curl http://localhost:3000/api/protected -H "Authorization: Bearer <your_jwt_token>"

You should get a success message with the decoded payload.

Finally, let's test the cached route. You’ll need to run a production build and run the file with node for this to work.

First, run the following command. The 1000 millisecond delay in the code will make this request take about a second.

curl -o /dev/null -s -w 'Total: %{time_total}s\n' http://localhost:3000/api/public-data

Immediately run the exact same command again. This time, the response will be almost instantaneous because our custom cache middleware served the response directly from its in-memory store, completely bypassing the setTimeout in the route handler. Run it a third time, and you'll see a similar near-instantaneous response.

Here's an example of what your terminal output should look like when testing the cache. The first request took around 1 second, but subsequent requests were a matter of milliseconds.

How to Create a Global Error Handler

You can define a single global error handler with app.onError(). This is useful for handling unexpected errors in a centralized way, such as validation failures.

Add the following code to your src/index.ts:

app.get('/users/:id', (c) => {
  const id = c.req.param('id')
  if (isNaN(Number(id))) {
    throw new Error('User ID must be a number.')
  }
  return c.text(`User ID is ${id}`)
})

app.onError((err, c) => {
  console.error(`${err}`)
  return c.json({
    success: false,
    message: err.message,
  }, 500)
})

Now, if you visit http://localhost:3000/users/abc, you will get a JSON error response instead of an uncaught exception.

How to Handle Validation with Zod

For robust APIs, data validation is essential. Hono integrates seamlessly with Zod, a popular TypeScript-first schema validation library.

Step 1: Install the necessary dependencies:

npm install zod @hono/zod-validator

Step 2: Replace src/index.ts with the validation example:

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

const app = new Hono()

// Define a Zod schema for the user creation data
const createUserSchema = z.object({
  username: z.string().min(3).max(20),
  email: z.string().email(),
  age: z.number().int().positive(),
  tags: z.array(z.string()).optional(),
})

app.post(
  '/users',
  zValidator('json', createUserSchema), // Use zValidator middleware
  (c) => {
    // The validated data is available on c.req.valid()
    const user = c.req.valid('json')
    console.log(`Creating user: ${user.username} with email ${user.email}`)
    return c.json({
      success: true,
      message: 'User created successfully!',
      user: user,
    }, 201)
  }
)

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

This is how the Zod validation is working:

1. We first define a schema called createUserSchema using z.object(). This schema is a blueprint for the expected data structure. We use Zod's built-in methods like z.string().min(3), z.string().email(), and z.number().int().positive() to specify validation rules for each property. For example, username must be a string between 3 and 20 characters, email must be a valid email format, and age must be a positive integer.

2. We then apply the zValidator middleware to our route handler. The first argument, 'json', tells the middleware to validate the incoming request's JSON body. The second argument, createUserSchema, tells it which schema to use for the validation.

3. The zValidator middleware automatically does the heavy lifting. When a request hits the /users endpoint, it will parse the JSON body and attempt to validate it against createUserSchema. If the data is invalid (for example, the email is not in a valid format), the middleware will immediately stop the request and return a 400 Bad Request status with a detailed error message, all without us having to write any manual checks.

4. If the data is valid, the middleware makes it available on the Context object, which we can access with c.req.valid('json'). Hono's type system ensures that this data is correctly typed according to the Zod schema, so we can use it safely in our handler.

Step 3: Run npm run dev.

Step 4: Test with curl (valid data):

curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"username": "testuser", "email": "test@example.com", "age": 25}'

This will return a success message.

Test with invalid data (for example, bad email):

curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"username": "testuser", "email": "invalid-email", "age": 25}'

This will automatically return a 400 status with a detailed error message from Zod.

How to Build a Full-Stack App with JSX

Hono supports server-side rendering with JSX, allowing you to build full-stack applications without needing a separate framework.

Step 1: Create src/components/Layout.tsx:

import { html } from 'hono/html'

export const Layout = (props: { title: string; children?: any }) => html`
  <!DOCTYPE html>
  <html>
    <head>
      <title>${props.title}</title>
      <style>
        body { font-family: sans-serif; background: #f4f4f4; color: #333; }
        .container { max-width: 800px; margin: 2rem auto; padding: 1rem; background: white; border-radius: 8px; }
        header { border-bottom: 1px solid #ccc; padding-bottom: 1rem; }
        footer { margin-top: 2rem; text-align: center; font-size: 0.8rem; color: #777; }
      </style>
    </head>
    <body>
      <div class="container">
        <header>
          <h1>${props.title}</h1>
        </header>
        <main>
          ${props.children}
        </main>
        <footer>
          <p>Powered by Hono</p>
        </footer>
      </div>
    </body>
  </html>
`

Step 2: Create src/components/PostItem.tsx:

export const PostItem = (props: { post: { id: number; title: string; author: string } }) => (
  <article style="border-bottom: 1px solid #eee; padding: 1rem 0;">
    <h3><a href={`/posts/${props.post.id}`}>{props.post.title}</a></h3>
    <p><em>By {props.post.author}</em></p>
  </article>
)

Step 3: Update src/index.tsx:

import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { Layout } from './components/Layout'
import { PostItem } from './components/PostItem'

const app = new Hono()

// Mock data
const posts = [
  { id: 1, title: 'Getting Started with Hono', author: 'Alice' },
  { id: 2, title: 'Advanced Middleware Patterns', author: 'Bob' },
  { id: 3, title: 'Deploying Hono to the Edge', author: 'Charlie' },
]

app.get('/', (c) => {
  return c.html(
    <Layout title="My Hono Blog">
      <h2>Recent Posts</h2>
      {posts.length > 0
        ? posts.map(post => <PostItem post={post} />)
        : <p>No posts yet!</p>
      }
    </Layout>
  )
})

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

Make sure to update the dev script in your package.json file to have src/index.tsx as the starting point.

"dev": "tsx watch src/index.tsx"

Step 4: Run npm run dev and visit http://localhost:3000. You will see a fully rendered blog page with the list of posts.

Deployment Guide for Hono

You have built your application, and now it's time to share it with the world. Here’s how you can deploy your Hono app to some of the most popular platforms.

How to Deploy to Node.js

For a traditional server environment, you can use the @hono/node-server adapter and a process manager like pm2 for production.

src/index.ts:

import { serve } from '@hono/node-server'
import app from './app' // Assuming your Hono app is in app.ts

serve({ fetch: app.fetch, port: 3000 })

You will then build your TypeScript to JavaScript and run pm2 start dist/index.js to run it in the background.

How to Deploy to Cloudflare Workers

Hono's true power lies in its portability. The create hono command can set up a project specifically for Cloudflare Workers.

Run the following command and select the cloudflare-workers template:

npm create hono@latest my-app-hono-cloudflare-worker

create-hono version 0.19.2
✔ Using target directory … my-app-hono-cloudflare-worker
? Which template do you want to use?
  aws-lambda
  bun
❯ cloudflare-workers
  cloudflare-workers+vite
  deno
  fastly
  lambda-edge

The setup process is identical to the Node.js example, but the project structure is optimized for Cloudflare.

Once the project is set up, you only need to type one command to deploy your application to Cloudflare:

wrangler deploy

This command will prompt you to log in to your Cloudflare account and will handle the entire deployment process automatically.

Conclusion

You've made it! We’ve covered a lot in this guide. You started with a professional project setup and moved all the way through advanced routing, context management, complex middleware patterns, robust data validation, and full-stack JSX components.

You now have the knowledge and the tools to build serious, production-ready applications with Hono. Its simple API doesn't limit its power. Rather, it enhances it by getting out of your way and letting you focus on building great features. And with its helpful portability, you can be confident that the application you build today can be deployed to the platforms of tomorrow.

The web development ecosystem will continue to evolve, but by building on Web Standards, Hono is a framework that's built to last.

To continue your journey, I highly recommend exploring the official Hono documentation, which is full of even more examples and guides.