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.

This inconsistency can lead to errors in your code and make it difficult to work with the data effectively. Imagine wrestling with unpredictable API responses as your application grows – it can quickly become a development nightmare!

This is where Zod comes in, offering a solution to effectively manage API data validation within React.

By the end of this tutorial, you’ll learn how to:

1. Set up and use Zod for API response validation in React.

2. Define schemas to validate and transform incoming data.

3. integrate Zod into API calls to improve data handling and prevent UI crashes.

Table of Contents

• What is Zod, and Why Use it for React API Calls?

• How to Generate a New TypeScript React Project

• Core Zod Concepts: Basic Usage, Types, and Validation

• How to Build Zod Schemas for API Responses

• How to Integrate Zod with React API Calls

• How to Render the User Interface (UI) and Handle Errors in React

• Conclusion

What is Zod, and Why Use it for React API Calls?

Zod is a powerful TypeScript-first library that simplifies data validation. It lets you define clear rules (schemas) for your expected data format.

Zod can then validate incoming data (often from API responses) to ensure it conforms to these rules. This validation process guarantees that the data adheres to your defined format, enhancing the reliability and integrity of your application.

Here's why Zod shines for React API validation:

• Clear schemas: Zod helps you define concise blueprints for API responses, enhancing readability and maintainability.

• Data validation: It offers powerful validation methods for various data types, enforcing rules like required fields and specific formats.

• Early error detection: It helps you detect data inconsistencies during API calls, preventing unexpected errors later in the application.

• Improved developer experience: It promotes type-safe coding, streamlining development time by eliminating manual data type checks.

• Single source of truth: And finally, Zod serves as a central point for data model definitions, ensuring consistency across the React application and reducing errors.

Using Zod, you can transform unpredictable API responses into clean, structured data, setting the stage for a smoother and more efficient development experience in your React applications.

How to Generate a New TypeScript React Project

Creating a new React project with TypeScript is straightforward. Here's how to get started. Execute the following command in your terminal:

npm create vite@latest my-react-app -- --template react-ts

Once the project is generated, navigate to the projects directory:

cd my-react-app
npm install
npm run dev

That’s it! Your React Project with TypeScript is now up and ready to use. Run the command below to install the Zod package:

npm install zod

Core Zod Concepts: Basic Usage, Types, and Validation

Zod helps you define clear expectations for your API responses using schemas. These schemas act like blueprints, specifying the types of data you expect to receive.

How to Build Schemas

Zod provides builder functions like z.string(), z.number(), and z.object() to create schemas. These functions define the data type you want for a specific field in your response.

import { z } from 'zod';
// Define basic data types
const userName = z.string().min(5).max(10); // String with min 5 and max 10 characters
const userAge = z.number().positive().int();  // Positive integer
const userEmail = z.string().email();        // Ensures a valid email format

console.log(userName.parse('John Doe'));       // Output: John Doe (valid)
console.log(userAge.parse(30));              // Output: 30 (valid)
console.log(userEmail.parse("johnDoe@gmail.com")); // Output: johnDoe@gmail.com (valid)

The code above defines three basic data types:

• userName: Represents a string with a minimum length of 5 characters and a maximum length of 10 characters.

• userAge: Represents a positive integer.

• userEmail: Ensures a valid email format.

Here’s the result of the code above:

How to Add Validation Rules

Zod allows you to chain methods like min, max, positive, int, and email to enforce specific rules on these data types. Here’s an example of an invalid string exceeding the maximum length:

console.log(userName.parse("Hello there, My Name is John Doe")); // Throws ZodError

The code throws a ZodError due to exceeding the maximum length of 10 strings, disrupting our application flow and eventually causing our application to break.

Here’s the image of the resulting code error:

Validating and Parsing

Zod offers two ways to check data against your schema:

• schema.parse(data): This method attempts to parse the data according to your schema. But if there's a validation error, it throws a ZodError. This can disrupt your application's flow, as illustrated in the previous example.

• schema.safeParse(data): This is the recommended approach. it parses the data and returns a ZodResult object. This object contains some key properties:

  • success: A boolean indicating whether the parsing was successful.

  • data: The parsed data itself (if the success property is true)

  • error: An error message if validation fails (if success property is false)

Here are two examples showcasing the usage of safeParse with both valid and invalid data so you can see the resulting outcomes.

First, lets see an example using safeParse with valid data:

const userSchema = z.object({
  name: userName,
  age: userAge,
  email: userEmail,
});

const userData = {
  name: "John Doe",
  age: 24,
  email: "johndoe@gmail.com"
};

const result = userSchema.safeParse(userData);

console.log(result); // ZodObject containing data and success status

This code defines a schema for user data using Zod, including properties for name, age, and email. It then attempts to parse a sample userData object using this schema via safeParse(). If successful, it prints the parsed data – otherwise, it logs an error message indicating the use of invalid data.

Here’s the image of the resulting code above:

Let’s now see how safeParse() handles invalid data using the same example as above. We’ll pass invalid data to the userSchema.safeParse() function to observe its behaviour.

const userSchema = z.object({
  name: userName,
  age: userAge,
  email: userEmail,
});

const userData = {
  name: "John Doe",
  age: 24,
  email: "johndoe.com" // invalid email
};

const result = userSchema.safeParse(userData);

console.log(result); // ZodObject containing error and success status

In this code example, we defined the userSchema. Next, we attempted to parse the userData object. But the parsing failed because the email property was not correctly formatted. Here’s a visual representation of the resulting output:

Unlike using parse, which completely halts your application upon encountering validation errors and throws a ZodError, utilizing safeParse allows you to gracefully handle these errors, ensuring uninterrupted operation.

How to Build Zod Schemas for API Responses

Building on our understanding of Zod’s core concepts, let’s create Zod schemas specifically for data received from API calls. We’ll leverage data from JSONPlaceholder, which offers information about posts.

Here’s a sample JSON response representing a post from JSONPlaceholder:

{
  "userId": 1,
  "id": 3,
  "title": "ea molestias quasi exercitationem repellat qui ipsa sit aut",
  "body": "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut"
}

Create a React component (give it a name that fits your project structure) to demonstrate building and utilizing Zod schemas for API validation. In this article, for illustrative purposes, we’ll call it the ZodApi component.

 import { z } from 'zod';

  const postSchema = z.object({
  userId: z.number().positive().int(),
  id: z.number().positive().int(),
  title: z.string(),
  body: z.string()
});

const postSchemaArray = z.array(postSchema); // Schema for array of posts

This code defines the expected structure of a single post object (postSchema) and an array of posts (postSchemaArray).

The following sections will explore integrating Zod with React components for API call handling and error management.

How to Integrate Zod with React API Calls

Let's bridge the gap between your defined Zod schemas and real API interactions.

We’ll need to update the code we wrote in the previous section to achieve our desired result in this section.

import { z } from 'zod';
import { useEffect } from 'react';

const postSchema = z.object({
  userId: z.number().positive().int(),
  id: z.number().positive().int(),
  title: z.string(),
  body: z.string()
});

const postSchemaArray = z.array(postSchema); // schema for an array of posts

type Posts = z.infer<typeof postSchemaArray>; // type of the posts

const ZodApi = () => {
  useEffect(() => {
    fetch("https://jsonplaceholder.typicode.com/posts")
      .then((response) => response.json())
      .then((posts: Posts) => {
        const validatedPosts = postSchemaArray.safeParse(posts); // remember to use safeParse instead of parse

        if (validatedPosts.success === false) {
          console.log("Validation Error:"validatedPosts.error);
          return;
        }

        // we can now safely use the posts
        console.log(validatedPosts.data);
      });
  }, []);
  return <div>ZodApi</div>;
};

export default ZodApi;

The ZodApi component demonstrates:

• Fetching data: Uses useEffect and fetch to get data from the API.

• Type safety: type Posts = z.infer<typeof postSchemaArray>; ensures type safety by defining the Posts type inferred from the schema postSchemaArray.

• Parsing with Zod: Validates the fetched data against the postSchemaArray using safeParse.

• Handling success: If validation succeeds, it provides access to clean data in validatedPosts.data for use in your component (UI, state, and so on).

Error handling: The if statement showcases a simple approach to Zod error handling. In a case where the validation is not successful (validatedPosts.success === false), a ZodError message is logged to the console.

Here’s a snapshot showing the resulting output in the console.

How to Render the User Interface (UI) and Handle Errors in React

In this section, you’ll learn how to render the UI based on our validated data and implement the error-handling mechanism using React states.

import { z } from "zod";
import { useEffect, useState } from "react";

const postSchema = z.object({
  userId: z.number().positive().int(),
  id: z.number().positive().int(),
  title: z.string(),
  body: z.string(),
});

const postSchemaArray = z.array(postSchema); // schema for an array of posts

type Posts = z.infer<typeof postSchemaArray>; // type of the posts

const ZodApi = () => {
  const [posts, setPosts] = useState<Posts>([]); // State to store validated posts
  const [error, setError] = useState(""); // State to store any errors
  useEffect(() => {
    fetch("https://jsonplaceholder.typicode.com/posts")
      .then((response) => response.json())
      .then((posts: Posts) => {
        const validatedPosts = postSchemaArray.safeParse(posts); // remember to use safeParse instead of parse

        if (validatedPosts.success === false) {
          console.log(validatedPosts.error.name);
          setError(validatedPosts.error.message); // set error state
          return;
        }

        // we can now safely use the validatedPosts 
        console.log(validatedPosts.data);
        setPosts(validatedPosts.data)
      });
  }, []);

  // Handle loading state (optional)
  if (!posts.length && !error) {
    return <div>Loading posts...</div>;
  }

  // Handle error state
  if (error) {
    return <div>Error fetching Data</div>; // Display user-friendly error message
  }

  return (
    <div>
      <h1>Posts</h1>
      <ol>
        {posts.map((post) => (
          <li key={post.id}>
            {post.title}
          </li>
        ))}
      </ol>
    </div>
  );
};

export default ZodApi;

In the code above, we’ve updated the ZodApi component to perform the following tasks:

• State declaration: The posts and error states hold the data and error (if any) gotten from the fetch request.

• Error handling: We use the posts and error state to show a “Loading posts…” message when the posts are being fetched and no error occurs, and display an error message when an error occurs.

• Rendering posts: It maps through the fetched posts and renders them on the UI.

Output:

After fetching the results, you should see the 100 posts displayed on your screen. If you followed the steps correctly, you'll find all 100 posts visible. If you encounter any issues, make sure the fetching process was successful.

Conclusion

By incorporating Zod into your React development workflow, you can build more robust and reliable applications.

Zod empowers you to catch mismatched data early on, preventing errors and saving valuable debugging time. Also, the user-friendly error messages given by Zod validation enhance your application’s overall user experience.

This is where Zod and React-Hook-Form come in as a dynamic duo, ready to take your forms to the next level.

Zod is a validation library that provides a concise and expressive syntax for defining data schemas, making it an excellent choice for validating form data.

On the other hand, React-Hook-Form is a lightweight form library for React that embraces uncontrolled components and simplifies form-building with its intuitive hooks-based API.

In this tutorial, you will learn how to build a type-safe form using React-Hook-Form for form management and Zod for both client-side and server-side validation.

Here's what we'll cover:

1. Getting Started
2. How to Define Form Types
3. How to Create a Form with react-hook-form
4. How to Integrate Zod for Schema Validation
5. How to Handle Server-Side Errors
6. Conclusion

Getting Started

To get started, clone the starter boilerplate for the project. Open up your terminal and run this command:

git clone --branch starter https://github.com/Giftea/zod-rhf-fcc.git

You can find the final version on GitHub here.

Once you've got the boilerplate on your local machine, run the following commands to install dependencies and start the project:

npm install
npm run dev

Point your browser to http://localhost:3000, and you'll be greeted by the starting page of our project.

localhost

How to Define Form Types

The /types.ts file will contain the types and schemas related to our form fields and their validation. Update the /types.ts file with the code below:

import { FieldError, UseFormRegister } from "react-hook-form";

export type FormData = {
    email: string;
    githubUrl: string;
    yearsOfExperience: number;
    password: string;
    confirmPassword: string;
  };

  export type FormFieldProps = {
    type: string;
    placeholder: string;
    name: ValidFieldNames;
    register: UseFormRegister<FormData>;
    error: FieldError | undefined;
    valueAsNumber?: boolean;
  };


  export type ValidFieldNames =
  | "email"
  | "githubUrl"
  | "yearsOfExperience"
  | "password"
  | "confirmPassword";

FormData represents the structure of the data expected in the form.

FormFieldProps defines the properties expected by the form field component (which we will build later on). It includes:

• type: The type of the input field (for example, text, password).
• placeholder: Placeholder text for the input field.
• name: The name of the field, which corresponds to one of the valid field names defined in the ValidFieldNames type.
• register: A function from react-hook-form (UseFormRegister<FormData>) used to register the input field with the form.
• error: Represents any validation error associated with the field. It can be undefined if there are no errors.
• valueAsNumber (optional): A boolean flag indicating whether the field value should be treated as a number. Defaults to undefined.

ValidFieldNames is a union type that enumerates the valid field names for the form. These correspond to the fields defined in the FormData type.

How to Create a Form with React-Hook-Form

Now that we have defined the types for the form, let's create a reusable form field component and the form component.

Create a Reusable Form Field Component

Let's create a reusable FormField component that handles rendering an input element, registering it with the form using react-hook-form, and displaying a validation error message when necessary.

Head on to the /app/components/FormField.tsx file and update the component:

import { FormFieldProps } from "@/types";

const FormField: React.FC<FormFieldProps> = ({
  type,
  placeholder,
  name,
  register,
  error,
  valueAsNumber,
}) => (
  <>
    <input
      type={type}
      placeholder={placeholder}
      {...register(name, { valueAsNumber })}
    />
    {error && <span className="error-message">{error.message}</span>}
  </>
);
export default FormField;

Imports:

• The component imports the FormFieldProps type from the @/types module. This type contains the expected properties for a form field, such as type, placeholder, name, register, error, and valueAsNumber.

Input Element:

• The component renders an <input> element with attributes set based on the provided props (type, placeholder, name).
• The ...register(name, { valueAsNumber }) syntax is used to register the input field with the form, enabling form state management.

Error Handling:

• If there is a validation error, a <span> element is rendered, displaying the error message.

Create the Form Component

The Form component will utilize the react-hook-form library to manage the form state. It modularizes form fields by using our reusable FormField component.

Navigate to app/components/Form.tsx and update it with the code below:

import { useForm } from "react-hook-form";
import { FormData } from "@/types";
import FormField from "./FormField";

function Form() {
  const {
    register,
    handleSubmit,
    formState: { errors },
    setError,
  } = useForm<FormData>();

  const onSubmit = async (data: FormData) => {
      console.log("SUCCESS", data);
  }

  return (
      <form onSubmit={handleSubmit(onSubmit)}>
        <div className="grid col-auto">
          <h1 className="text-3xl font-bold mb-4">
            Zod & React-Hook-Form
          </h1>
          <FormField
            type="email"
            placeholder="Email"
            name="email"
            register={register}
            error={errors.email}
          />

          <FormField
            type="text"
            placeholder="GitHub URL"
            name="githubUrl"
            register={register}
            error={errors.githubUrl}
          />

          <FormField
            type="number"
            placeholder="Years of Experience (1 - 10)"
            name="yearsOfExperience"
            register={register}
            error={errors.yearsOfExperience}
            valueAsNumber
          />

          <FormField
            type="password"
            placeholder="Password"
            name="password"
            register={register}
            error={errors.password}
          />

          <FormField
            type="password"
            placeholder="Confirm Password"
            name="confirmPassword"
            register={register}
            error={errors.confirmPassword}
          />
          <button type="submit" className="submit-button">
            Submit
          </button>
        </div>
      </form>
  );
}

export default Form;

Imports:

• The useForm hook provides functionality for managing form state and validation.
• FormData represents the structure of the form data.
• FormField is our reusable form field component.

Form Component:

• Form-related functions and state variables are destructured from the useForm hook, which is explicitly typed with FormData to define the shape of the form data.
• Within the form, the FormField components are rendered for different input fields such as email, GitHub URL, years of experience, password, and confirm password.

Run Code:

Import the Form component into /app/page.tsx file:

"use client";
import Form from "./components/Form";

function Home() {

  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
     <Form />
    </main>
  );
}

export default Home;

Visit http://localhost:3000/ to view the form:

http://localhost:3000/

In summary, our Form component is a basic form structure that uses the react-hook-form library for state management and employs a reusable FormField component to handle the rendering and validation of individual form fields.

How to Integrate Zod for Schema Validation

Zod stands out as a schema declaration and validation library, with TypeScript as its primary focus. The term "schema" encompasses various data types, ranging from strings, numbers, and booleans to more complex objects.

Define a Form Schema with Zod

Let's create a TypeScript-backed form schema using Zod for our form structure.

Head to your /types.ts file, add the new imports, and create a user schema with the code below:

 import { z, ZodType } from "zod"; // Add new import

 export const UserSchema: ZodType<FormData> = z
  .object({
    email: z.string().email(),
    githubUrl: z
      .string()
      .url()
      .includes("github.com", { message: "Invalid GitHub URL" }),
    yearsOfExperience: z
      .number({
        required_error: "required field",
        invalid_type_error: "Years of Experience is required",
      })
      .min(1)
      .max(10),
    password: z
      .string()
      .min(8, { message: "Password is too short" })
      .max(20, { message: "Password is too long" }),
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Passwords do not match",
    path: ["confirmPassword"], // path of error
  });

Imports:

• z is an instance of the Zod object.
• ZodType is a generic type that represents a Zod schema type for a specific data structure.

User Schema:

• export const UserSchema: ZodType<FormData> = ...: The UserSchema represents a Zod type that corresponds to the structure defined by the FormData type.
• z.object({...}): This part defines an object schema using Zod. The object has several fields, each with its own validation rules.
• Inside the object, each field is defined with its own validation rules using Zod methods like z.string(), z.url(), z.number(), and z.min(). Optional custom error messages are provided for some of the fields.
• z.refine((data) => data.password === data.confirmPassword, { /* ... */ });: Adds a refinement to the schema to check if the password and confirmPassword fields match. If not, a custom error message is provided, and the error is associated with the confirmPassword field.

How to Integrate Zod with React-Hook-Form for validation

Now that we've set up the Zod schema for the form, let's integrate it with our existing Form component. To do this, we'll use zodResolver from the [@hookform](https://www.npmjs.com/package/@hookform/resolvers) library.

zodResolver is a resolver function that integrates the Zod schema validation with the form validation process.

Head over to the app/components/Form.tsx file and update it with the code below:

// Update imports
import { FormData, UserSchema } from "@/types";
import { zodResolver } from "@hookform/resolvers/zod";

function Form() {
  const {
    register,
    handleSubmit,
    formState: { errors },
    setError,
  } = useForm<FormData>({
    resolver: zodResolver(UserSchema), // Apply the zodResolver
  });

{/* Existing Code...*/}

}

If you try submitting the form with empty input fields, you will see error messages on the browser.

Error Messages - http://localhost:3000/

Additionally, our custom error messages, such as prompting users to provide a valid GitHub URL and checking if the passwords match, are demonstrated in the image below:

Custom Error Messages - http://localhost:3000/

How to Handle Server-Side Errors

When creating forms, data integrity and type safety are very important, given that submitted data goes to the website's server. This leads us to the significance of handling server-side errors — an extra security measure to make sure data from the client is accurate and non-malicious.

How to Implement Server-Side Validation

To implement server-side validation, we will leverage Next.js' backend capabilities to build a simple server. This server will receive and validate the data submitted through our form.

Navigate to app/api/form/route.ts and include the code below:

import { UserSchema } from "@/types";
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  // Retrieve the JSON data from the request body
  const body = await request.json();

  // Use Zod to validate the received data against the UserSchema
  const result = UserSchema.safeParse(body);

  // Check if the validation is successful
  if (result.success) {
    return NextResponse.json({ success: true });
  }

  // If validation errors, map them into an object
  const serverErrors = Object.fromEntries(
    result.error?.issues?.map((issue) => [issue.path[0], issue.message]) || []
  );

  // Respond with a JSON object containing the validation errors
  return NextResponse.json({ errors: serverErrors });
}

Imports:

• The UserSchema we defined earlier is imported.
• NextResponse from the next/server module, which allows us to craft server responses in a Next.js environment.

POST Function:

• const body = await request.json(): Retrieves the JSON data from the request body and stores it in the body variable.
• const result = UserSchema.safeParse(body): Utilizes the safeParse method provided by Zod to validate the received data against the UserSchema. The result contains information about whether the validation was successful and, if not, details about the validation issues.
• if (result.success) { return NextResponse.json({ success: true }); }: If the validation is successful, a JSON response with { success: true } is sent.
• const serverErrors = Object.fromEntries(/* ... */): If there are validation errors, the code maps them into an object with field names and corresponding error messages.
• return NextResponse.json({ errors: serverErrors }): Responds with a JSON object containing the validation errors.

In your terminal, stop running the project and run npm run dev again to restart the server.

How to Integrate Server-Side Validation

To integrate the server-side validation, we have to update the onSubmit function in the Form component.

Head over to the /app/components/Form.tsx file and update the imports and onSubmit function:

// Update import
import { FormData, UserSchema, ValidFieldNames } from "@/types";  
import axios from "axios";

function Form() {
{/* Existing Code... */}

  const onSubmit = async (data: FormData) => {
    try {
      const response = await axios.post("/api/form", data); // Make a POST request
      const { errors = {} } = response.data; // Destructure the 'errors' property from the response data

      // Define a mapping between server-side field names and their corresponding client-side names
      const fieldErrorMapping: Record<string, ValidFieldNames> = {
        email: "email",
        githubUrl: "githubUrl",
        yearsOfExperience: "yearsOfExperience",
        password: "password",
        confirmPassword: "confirmPassword",
      };

      // Find the first field with an error in the response data
      const fieldWithError = Object.keys(fieldErrorMapping).find(
        (field) => errors[field]
      );

      // If a field with an error is found, update the form error state using setError
      if (fieldWithError) {
        // Use the ValidFieldNames type to ensure the correct field names
        setError(fieldErrorMapping[fieldWithError], {
          type: "server",
          message: errors[fieldWithError],
        });
      }
    } catch (error) {
      alert("Submitting form failed!");
    }
  };
{/* Existing Code... */}
}

• axios is used to make a POST request to the server endpoint /api/form with the form data.
• The errors object is extracted from the response data.
• A mapping (fieldErrorMapping) between field names and their corresponding ValidFieldNames is defined.
• It then checks if there are any errors related to form fields by iterating over the fieldErrorMapping and finding the first field with an error.
• If a field with an error is found, the setError function from react-hook-form is used to set an error for the corresponding field. The error type is marked as "server," and the error message comes from the server response.
• If there's an error in the entire try block, it catches the error and displays an alert: "Submitting form failed!"

Now, to test if we can receive errors from the server, we'll deliberately send improperly formatted data to the server. In your onSubmit function, replace the data object with the incorrect data in the code block below:

{/* Existing Code...*/}
  const onSubmit = async (data: FormData) => {

    try {
      // Update data sent in axios with incorrect data
      const response = await axios.post("/api/form", {
        email: "Not an email",
        githubUrl: "Not a URL",
        yearsOfExperience: "Hello",
        password: 1234,
        confirmPassword: 1234,
      }); // Make a POST request

{/* Existing Code...*/}
}

Fill the form in the browser normally and submit the form.

Inspect the "Network" tab within the browser's developer tools. You'll find error messages coming directly from the server, as demonstrated in the image below:

Server errors - http://localhost:3000/

If you're not getting any response from your server, remember to stop running your project in your terminal and run npm run dev again to re-start the server.

Conclusion

In this tutorial, we built a form with React-Hook-Form and validated it with Zod. With Zod, we explored schema validation, customized error messages, and server-side errors. The integration of React-Hook-Form and Zod presents a powerful, developer-friendly solution to creating resilient forms.

You can reach out to me on Twitter if you have any questions.

You can check out the source code and the deployed app.

Resources:

• Zod Documentation
• Zod Error Handling
• React-Hook-Form Documentation
• Hookform Resolvers