Next-zod-route NPM

A fork from next-safe-route that uses zod instead of typeschema.

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.
🔗 Extensible: Compatible with any validation library supported by TypeSchema.
🧪 Fully Tested: Extensive test suite to ensure everything works reliably.

Installation

npm install next-zod-route

The library only works with zod for schema validation.

Usage

// app/api/hello/route.ts
import { createZodRoute } from 'next-zod-route';
import { z } from 'zod';

const paramsSchema = z.object({
  id: z.string(),
});

const querySchema = z.object({
  search: z.string().optional(),
});

const bodySchema = z.object({
  field: z.string(),
});

export const GET = createZodRoute()
  .params(paramsSchema)
  .query(querySchema)
  .body(bodySchema)
  .handler((request, context) => {
    const { id } = context.params;
    const { search } = context.query;
    const { field } = context.body;

    return Response.json({ id, search, field }), { status: 200 };
  });

To define a route handler in Next.js:

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

Advanced Usage

Middleware

You can add middleware to your route handler with the use method.

const safeRoute = createSafeRoute()
  .use(async (request, context) => {
    return { user: { id: 'user-123', role: 'admin' } };
  })
  .handler((request, context) => {
    const user = context.data.user;
    return Response.json({ user }, { status: 200 });
  });

Ensure that the middleware returns an object. The returned object will be merged with the context object.

Custom Error Handler

You can specify a custom error handler function with the handleServerError method.

To achieve this, define a custom error handler when creating the safeRoute:

class CustomError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'CustomError';
  }
}

const safeRoute = createSafeRoute({
  handleServerError: (error: Error) => {
    if (error instanceof CustomError) {
      return new Response(JSON.stringify({ message: error.name, details: error.message }), { status: 400 });
    }

    return new Response(JSON.stringify({ message: 'Something went wrong' }), { status: 400 });
  },
});

const GET = safeRoute.handler((request, context) => {
  // This error will be handled by the custom error handler
  throw new CustomError('Test error');
});

By default, to avoid any information leakage, the error handler will always return a generic error message.