Zod can implement type-safe API routing in Next.js. First, define the schema of the request and response, then verify and inject the type through the higher-order function withValidation, and finally use this encapsulation in the routing to ensure that the input and output are verified. Schema can also be reused to generate front-end types to ensure consistency. 1. Define the Schema verification request body, query parameters and response structure; 2. Create the withValidation function to automatically parse and type the request; 3. Apply this function in API routing to achieve full-link type safety; 4. Optionally verify the response body and encapsulate the tool function; 5. The front-end directly imports the types generated by Zod to ensure that the front-end and back-end types are consistent, thereby improving the development experience and project quality.

Next.js makes building full-stack applications simple, but by default, API routing is weak-type—you can easily make errors in request body parsing, query parameters, or response formats. Combined with Zod, you can implement fully type-safe API routing, with compile-time checks and automatic prompts from requests to responses.

Here is a practical way to implement type-safe API routing using Zod in Next.js.

? Schema that defines requests and responses

The core of Zod is to define verifiable data structures. For API routing, we usually need to verify:

• Query parameters ( query )
• Request body ( body )
• response

 // lib/schemas/userSchema.ts
import { z } from 'zod';

export const createUserSchema = z.object({
  body: z.object({
    name: z.string().min(1),
    email: z.string().email(),
  }),
  query: z.object({
    apiKey: z.string().min(1),
  }).optional(),
});

export type CreateUserInput = z.infer<typeof createUserSchema>;

This schema defines the structure required by POST /api/users .

?? Create a type-safe API processor

We encapsulate a higher-order function, automatically parses and type req.body and req.query .

 // lib/api/handler.ts
import { NextApiRequest, NextApiResponse } from 'next';
import { ZodSchema, ZodError } from 'zod';

type Handler<T> = (
  req: NextApiRequest & { body: T[&#39;body&#39;]; query: T[&#39;query&#39;] },
  res: NextApiResponse
) => Promise<void> | void;

export function withValidation<T extends { body?: any; query?: any }>(
  schema: ZodSchema<T>,
  handler: Handler<T>
) {
  return async (req: NextApiRequest, res: NextApiResponse) => {
    try {
      const data = schema.parse({
        body: req.method !== &#39;GET&#39; ? req.body : undefined,
        query: req.query,
      });

      return handler(req as any, res);
    } catch (error) {
      if (error instanceof ZodError) {
        return res.status(400).json({
          error: &#39;Validation failed&#39;,
          details: error.errors,
        });
      }
      return res.status(500).json({ error: &#39;Internal server error&#39; });
    }
  };
}

This withValidation function will:

• Verify input
• "inject" the correct body and query types at the type level
• Catch Zod error and return 400

? Actual use: Type-safe API routing

 // pages/api/users.ts
import { NextApiRequest, NextApiResponse } from 'next';
import { withValidation } from '@/lib/api/handler';
import { createUserSchema } from '@/lib/schemas/userSchema';

export default withValidation(
  createUserSchema,
  async function createUser(
    req: NextApiRequest & { body: { name: string; email: string } },
    res: NextApiResponse
  ) {
    const { name, email } = req.body;

    // Here type safety: name and email have been guaranteed to be string by Zod
    // Can be inserted safely into the database...

    return res.status(201).json({
      id: '123',
      name,
      email,
    });
  }
);

Now:

• If the front-end passes name: null , it will be rejected by Zod
• In VS Code, req.body. will have a complete automatic completion
• Any access to req.body.phone will report an error (unless schema is defined)

? Optional: Unified response format response verification

Going further, you can also verify the output to prevent unexpected return of sensitive fields:

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

// Const result = { id: '123', name, email };
const parsed = createResponseSchema.parse(result); // Make sure the output structure is correct return res.status(201).json(parsed);

You can even encapsulate a validResponse(schema, data) tool function.

? Tips: Reuse front-end types

Zod schema can generate TypeScript types, so the front-end can directly import:

 // frontend component
import type { CreateUserInput } from '@/lib/schemas/userSchema';

const data: CreateUserInput['body'] = {
  name: 'Alice',
  email: 'alice@example.com',
}; // The types are exactly the same, and you don’t have to worry about the backend changing field

Basically that's it. With a small amount of Zod encapsulation, Next.js API routing can be obtained:

• Automatic verification of request body/query parameters
• Full link type safety
• Better development experience (automatic completion, early error reporting)
• Reduce runtime errors

Not complicated, but it can greatly improve the quality of the project.

The above is the detailed content of Type-Safe API Routes in Next.js with Zod. For more information, please follow other related articles on the PHP Chinese website!