next-zod-route

A fork from next-safe-route that uses zod for schema validation.

next-zod-route is a utility library for Next.js that provides type-safety and schema validation for Route Handlers/API Routes.

Features

• ✅ Schema Validation: Automatically validates request parameters, query strings, and body content with built-in error handling.
• 🧷 Type-Safe: Works with full TypeScript type safety for parameters, query strings, and body content.
• 😌 Easy to Use: Simple and intuitive API that makes defining route handlers a breeze.
• 🔄 Flexible Response Handling: Return Response objects directly or return plain objects that are automatically converted to JSON responses.
• 🧪 Fully Tested: Extensive test suite to ensure everything works reliably.

Installation

1npm install next-zod-route zod

Or using your preferred package manager:

1pnpm add next-zod-route zod

1yarn add next-zod-route zod

Usage

1// app/api/hello/route.ts
2import { createZodRoute } from 'next-zod-route';
3import { z } from 'zod';
4
5const paramsSchema = z.object({
6  id: z.string(),
7});
8
9const querySchema = z.object({
10  search: z.string().optional(),
11});
12
13const bodySchema = z.object({
14  field: z.string(),
15});
16
17export const GET = createZodRoute()
18  .params(paramsSchema)
19  .query(querySchema)
20  .handler((request, context) => {
21    // Next.js passes params as a promise, but next-zod-route unwraps it for you
22    const { id } = context.params;
23    const { search } = context.query;
24
25    // Return a Response object directly
26    return Response.json({ id, search }), { status: 200 };
27
28    // Or return a plain object that will be converted to a JSON response
29    // return { id, search };
30  });
31
32export const POST = createZodRoute()
33  .params(paramsSchema)
34  .query(querySchema)
35  .body(bodySchema)
36  .handler((request, context) => {
37    // Next.js 15 use promise, but with .params we already unwrap the promise for you
38    const { id } = context.params;
39    const { search } = context.query;
40    const { field } = context.body;
41
42    return Response.json({ id, search, field }), { status: 200 };
43  });

To define a route handler in Next.js:

1. Import createZodRoute and zod.
2. Define validation schemas for params, query, and body as needed.
3. Use createZodRoute() to create a route handler, chaining params, query, and body methods.
4. Implement your handler function, accessing validated and type-safe params, query, and body through context.

Supported Body Formats

next-zod-route supports multiple request body formats out of the box:

• JSON: Automatically parses and validates JSON bodies.
• URL Encoded: Supports application/x-www-form-urlencoded data.
• Multipart Form Data: Supports multipart/form-data, enabling file uploads and complex form data parsing.

The library automatically detects the content type and parses the body accordingly. For GET and DELETE requests, body parsing is skipped.

Response Handling

You can return responses in two ways:

1. Return a Response object directly:

1return Response.json({ data: 'value' }, { status: 200 });

2. Return a plain object that will be automatically converted to a JSON response with status 200:

1return { data: 'value' };

Advanced Usage

Middleware

You can add middleware to your route handler with the use method. Middleware functions can add data to the context that will be available in your handler.

1const authMiddleware = async ({ request }) => {
2  // Get the token from the request headers
3  const token = request.headers.get('authorization')?.split(' ')[1];
4
5  // Validate the token and get the user
6  const user = await validateToken(token);
7
8  // Return the user to be added to the context
9  return { user };
10};
11
12const permissionsMiddleware = async () => {
13  return { permissions: ['read', 'write'] };
14};
15
16export const GET = createZodRoute()
17  .use(authMiddleware)
18  .use(permissionsMiddleware)
19  .handler((request, context) => {
20    // Access middleware data from context.data
21    const { user, permissions } = context.data;
22
23    return Response.json({ user, permissions });
24  });

Middleware functions should return an object. The returned object will be merged with the context's data property.

Custom Error Handler

You can specify a custom error handler function to handle errors thrown in your route handler:

1import { createZodRoute } from 'next-zod-route';
2
3// Create a custom error class
4class CustomError extends Error {
5  constructor(
6    message: string,
7    public status: number = 400,
8  ) {
9    super(message);
10    this.name = 'CustomError';
11  }
12}
13
14// Create a route with a custom error handler
15const safeRoute = createZodRoute({
16  handleServerError: (error: Error) => {
17    if (error instanceof CustomError) {
18      return new Response(JSON.stringify({ message: error.message }), { status: error.status });
19    }
20
21    // Default error response
22    return new Response(JSON.stringify({ message: 'Internal server error' }), { status: 500 });
23  },
24});
25
26export const GET = safeRoute.handler((request, context) => {
27  // This error will be caught by the custom error handler
28  throw new CustomError('Something went wrong', 400);
29});

By default, if no custom error handler is provided, the library will return a generic "Internal server error" message with a 500 status code to avoid information leakage.

Validation Errors

When validation fails, the library returns appropriate error responses:

• Invalid params: { message: 'Invalid params' } with status 400
• Invalid query: { message: 'Invalid query' } with status 400
• Invalid body: { message: 'Invalid body' } with status 400

Tests

Tests are written using Vitest. To run the tests, use the following command:

1pnpm test

Contributing

Contributions are welcome! For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.