gem-hunter

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

• ✅ Schema Validation: Automatically validate request parameters, query strings, and body content with built-in error handling.
• 🧷 Type-Safe: Work 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.

npm install next-safe-route

The library natively works with zod for schema validation, but you can use any other validation library that is supported by TypeSchema, as long as you install its respective adapter.

// app/api/hello/route.ts
import { createSafeRoute } from 'next-safe-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 = createSafeRoute()
  .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:

1. Import createSafeRoute and your validation library (e.g., zod).
2. Define validation schemas for params, query, and body as needed.
3. Use createSafeRoute() 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.

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

pnpm test

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

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