Next Zod API

:warning: This package is for the newer App Router which is introduced in Next.JS 13. If you are using the older Pages Router, use next-better-api instead.

A Next.JS API handler that validates request and response using Zod.

Simplify the creation of API endpoints in Next.JS with a method endpoint that handles validation of query parameters, body payload (json, form data, etc), and the response.

This package was intended as an App Router compatible rewrite of next-better-api so I kept the endpoint function work the same way.

Jump to example code:

• GET Example
• PUT Example with request body
• POST Example with form data
• CORS Helper

Installation

1npm install next-zod-api

or

1yarn add next-zod-api

Usage

All parameters

1import { endpoint, z } from 'next-zod-api';
2
3export const (GET|POST|PUT|PATCH|DELETE) = endpoint({
4    /* 
5      (optional) These are all optional validators using Zod
6    */
7    querySchema: z(...),
8    bodySchema: z(...),
9    responseSchema: z(...)
10}, async ({ params, query, body, headers }) => {
11    /*
12      params: Route parameters such as [slug] in /path/[slug]/route.js
13      query: GET parameters: ?key=value&key2=value2
14      body: POST request data parsed (json / multipart/form-data / text)
15      headers: Request headers parsed into an object {key: value}
16    */
17    return {
18        status: (HTTP_STATUS_CODE),
19        body: {OUTPUT_AS_JSON},
20        headers:{RESPONSE_HEADERS}
21    };
22});

GET Example

/app/api/user/route.js

1import { endpoint, z } from 'next-zod-api';
2
3export const GET = endpoint({
4    querySchema: z.object({
5        sort: z.string().optional(),
6        page: z.number().optional(),
7        perPage: z.number().optional()
8    }),
9    responseSchema: z.object({
10        users: z.array(
11            z.object({
12                id: z.string(),
13                name: z.string(),
14                email: z.string().email(),
15                active: z.boolean()
16            })
17        )
18    })
19}, async ({ query }) => {
20    const users = await getUsers({
21        sort: query.sort,
22        page: query.page,
23        perPage: query.perPage
24    });
25
26    return {
27        status: 200,
28        body: {
29            users
30        }
31    };
32});

PUT Example with request body

/app/api/user/[user_id]/route.js

1import { endpoint, z } from 'next-zod-api';
2
3export const PUT = endpoint({
4    bodySchema: z.object({
5        name: z.string(),
6        email: z.string().email()
7    }),
8    responseSchema: z.object({
9        success: z.boolean(),
10        user: z.object({
11            id: z.string(),
12            name: z.string(),
13            email: z.string().email(),
14            active: z.boolean()
15        })
16    })
17}, async ({ params, body }) => {
18    const user = await updateUser(params.user_id, body);
19
20    return {
21        status: 201,
22        body: {
23            success: true,
24            user
25        }
26    };
27});

POST Example with form data

/app/api/user/[user_id]/avatar/route.js

1import { endpoint, z } from 'next-zod-api';
2import fs from 'fs';
3
4export const POST = endpoint({
5    bodySchema: z.object({
6        file: z.any().refine(value => {
7            return value.constructor.name === 'File';
8        }, {
9            message: 'Must be a file',
10        }),
11        /* Or alternatively, if the browser 'File' object is available in your environment: */
12        file: z.instanceof(File)
13    }),
14    responseSchema: z.object({
15        success: z.boolean(),
16        fileName: z.string()
17    })
18}, async ({ params, body }) => {
19    const { file } = body;
20    const fileName = file.name;
21    const bytes = await file.arrayBuffer()
22    const buffer = Buffer.from(bytes)
23    fs.writeFileSync('./uploads/'+fileName, buffer)
24
25    return {
26        status: 200,
27        body: {
28            success: true,
29            fileName
30        }
31    };
32});

CORS Helper

The package includes a helper function to handle Cross-Origin Resource Sharing (CORS) in your API endpoints. CORS is a mechanism that allows resources on a web page to be requested from another domain outside the domain from which the resource originated.

Import the cors function from the package and use it to create CORS headers and a preflight response for your API endpoints.

Here's how to use it:

1import { endpoint, cors, z } from 'next-zod-api';
2const { preflight, corsHeaders } = cors();
3export const OPTIONS = preflight;

And add the CORS headers to your responses:

1export const POST = endpoint({
2//...
3}, async ()=>{
4    return {
5        body: ...,
6        headers: corsHeaders
7    }
8});

The cors function accepts an optional configuration object where you can specify the origin and allowHeaders:

1const { preflight, corsHeaders } = cors({
2    origin: "https://example.com",
3    allowHeaders: "Content-Type, Authorization, X-Requested-With"
4});

• origin (optional): Configures the Access-Control-Allow-Origin CORS header. Defaults to "*", which allows any origin.
• allowHeaders (optional): Configures the Access-Control-Allow-Headers CORS header. Defaults to "Content-Type, Authorization, X-Requested-With", which allows these headers to be used in the actual request.

The cors function returns an object with two properties:

• corsHeaders: An object with CORS headers that can be included in a response.
• preflight: A function that returns a preflight response, which is a simple response with a 200 status and the CORS headers. You can use this for handling OPTIONS requests, which are sent by browsers as part of the CORS preflight process.

License

MIT