Getting started

Initialize client

To use Next REST Framework you need to initialize the client somewhere in your Next.js project. The client exposes all functionality of the framework you will need:

// src/next-rest-framework/client.ts

import { NextRestFramework } from 'next-rest-framework';

export const { defineCatchAllHandler, defineEndpoints } = NextRestFramework({
  //  apiRoutesPath: "src/pages/api", // Only needed if using the src/ folder.
});

The complete API of the initialized client is the following:

Name	Description
`defineCatchAllHandler`	A function used to generate your single catch-all API route. Must be used in the root of your API routes folder in the following path `pages/api/[[...next-rest-framework]].ts`.
`defineEndpoints`	Used for all other API routes that you want to use Next REST Framework for. Can also be used in other catch-all API routes.

Initialize catch-all handler

To initialize Next REST Framework you need to export and call the defineCatchAllHandler function from a root-level optional catch-all API route:

// src/pages/api/[[...next-rest-framework]].ts

import { defineCatchAllHandler } from 'next-rest-framework/client';

export default defineCatchAllHandler();

This is enough to get you started. By default Next REST Framework gives you three API routes with this configuration:

/api: Swagger UI using the auto-generated OpenAPI spec.
/api/openapi.json: An auto-generated openapi.json document.
/api/openapi.yaml: An auto-generated openapi.yaml document.
A local openapi.json file that will be generated as you run npx next-rest-framework generate or call any of the above endpoints in development mode. This file should be under version control and you should always keep it in the project root. It will dynamically update itself as you develop your application locally and is used by Next REST Framework when you run your application in production. Remember that it will be dynamically regenerated every time you call any of the above endpoints in development mode. A good practice is also to generate this file before you run next build when going to production, so your build script would look something like: npx next-rest-framework generate && next build.

The reserved OpenAPI paths are configurable with the Config options that you can pass for your NextRestFramework client. You can also use your existing catch-all logic simply by passing a Route config to your defineCatchAllHandler if you want to use e.g. custom 404 handlers, redirections etc.

Add an API Route

// src/pages/api/todos.ts

import { defineEndpoints } from 'next-rest-framework/client';
import { z } from 'zod';

const todoSchema = z.object({
  id: z.string(),
  name: z.string(),
  completed: z.boolean()
});

export default defineEndpoints({
  GET: {
    output: [
      {
        status: 200,
        contentType: 'application/json',
        schema: z.array(todoSchema)
      }
    ],
    handler: ({ res }) => {
      // Any other content type will lead to TS error.
      res.setHeader('content-type', 'application/json');

      // Any other status or JSON format will lead to TS error.
      res.status(200).json([
        {
          id: 'foo',
          name: 'bar',
          completed: true
        }
      ]);
    }
  },
  POST: {
    input: {
      contentType: 'application/json',
      body: z.object({
        name: z.string()
      }),
      query: z.object({
        page: z.string()
      })
    },
    output: [
      {
        status: 201,
        contentType: 'application/json',
        schema: todoSchema
      }
    ],
    handler: ({
      res,
      req: {
        body: {
          name // Any other attribute will lead to TS error.
        },
        query: {
          page // Any other attribute will lead to TS error.
        }
      }
    }) => {
      // Any other content type will lead to TS error.
      res.setHeader('content-type', 'application/json');

      // Any other status or JSON format will lead to TS error.
      res.status(201).json({
        id: 'foo',
        name,
        completed: false
      });
    }
  }
});

These type-safe endpoints will be now auto-generated to your OpenAPI spec and Swagger UI!

Config options

The optional config options allow you to customize Next REST Framework. The following options can be passed as a parameter for your NextRestFramework client in an object:

Name	Description
`openApiSpecOverrides`	An OpenAPI Object that can be used to override and extend the auto-generated specification.
`openApiJsonPath`	Custom path for serving `openapi.json` file. Defaults to `/api/openapi.json`.
`openApiYamlPath`	Custom path for serving `openapi.yaml` file. Defaults to `/api/openapi.yaml`.
`swaggerUiPath`	Custom path for service Swagger UI. Defaults to `/api`.
`swaggerUiConfig`	A SwaggerUI config object for customizing the generated SwaggerUI.
`exposeOpenApiSpec`	Setting this to `false` will serve none of the OpenAPI documents neither the Swagger UI. Defaults to `true`.
`middleware`	A global middleware for all of your API routes. See Global middleware for more information.
`errorHandler`	A Global error handler for all of your API routes. Defaults to a basic error handler logging the errors in non-production mode.
`suppressInfo`	Setting this to `true` will suppress all informational logs from Next REST Framework. Defaults to `false`.
`apiRoutesPath`	Absolute path to the directory where your API routes are located - defaults to `pages/api`.

Route config

The route config parameters define an individual route, applicable for all endpoints (methods) that are using that route:

Name	Description	Required
`GET \\| PUT \\| POST \\| DELETE \\| OPTIONS \\| HEAD \\| PATCH \\| TRACE`	A Method handler object.	`true`
`middleware`	A Middleware function that takes in the return values from your Global middleware.	`false`
`errorHandler`	A Route error handler for this API route, overriding the Global error handler.	`false`
`openApiSpecOverrides`	An OpenAPI Path Item Object that can be used to override and extend the auto-generated and higher level specifications.	`false`

Method handlers

The method handler parameters define an individual endpoint:

Name	Description	Required
`input`	An Input object object.	`false`
`output`	An array of Output objects.	`true`
`middleware`	A Middleware function that takes in the return values from both your Global middleware and Route middleware.	`false`
`handler`	Your Handler function that takes in your typed request, response and Middleware parameters and contains all of your business logic.	`true`
`errorHandler`	A Method error handler for this method, overriding both the Global error handler and Route error handler.	`false`
`openApiSpecOverrides`	An OpenAPI Operation object that can be used to override and extend the auto-generated and higher level specifications.	`false`

Input

The input object is used for the validation of the incoming request:

Name	Description	Required
`contentType`	The content type that the request must have - request with no content type or incorrect content type will get an error response.	`true`
`body`	A Zod schema describing the format of the request body.	`true`
`query`	A Zod schema describing the format of the query parameters. Note that Next.js parses the query string into an object containing either strings or arrays of strings.	`false`

Output object

The output objects define what kind of responses you are allowed to return from your API handlers:

Name	Description	Required
`status`	A possible status code that your API can return - using other status codes will lead to a TS error.	`true`
`contentType`	The content type of the response - using other content-types will lead to a TS error.	`true`
`schema`	A Zod schema describing the format of the response data. A response format not matching to the schema will lead to a TS error.	`true`

Handler

The handler function takes care of your actual business logic, supporting both synchronous and asynchronous execution and taking in an object with three strongly typed parameters:

Name	Description
`req`	A strongly-typed `NextApiRequest` object containing the typed body and query parameters of your request.
`res`	A strongly-typed `NextApiResponse` object that allows you to use only pre-defined status codes, `Content-Type` headers and response data formats from the current method handler.
`params`	An object containing the strongly-typed combined response of your Global middleware, Route middleware and Method middleware. The parameters can also be overridden in the different middleware layers with the Method middleware taking precedence over the Route middleware and route middleware taking precedence over Global middleware

Middlewares

The middleware functions can be used for any kind of middleware logic, like adding authentication etc. for your API. In addition, they can be used to add additional typed parameters for your API route handlers. They support both asynchronous and synchronous execution.

// A global middleware, route middleware or method middleware.
middleware: () => ({
  foo: 'bar'
});
// A method handler (given that the middleware above is either in the same API route or method, or is a global middleware).
handler: ({
  params: {
    foo // string
  }
}) => {
  // Your logic.
};

Global middleware

The global middleware function takes in an object with two attributes and optionally returns an object of any form:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.

Route middleware

The route middleware function takes in an object with three attributes and optionally returns an object of any form:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.
`params`	The type of an object returned by your Global middleware.

Method middleware

The method middleware function takes in an object with three attributes and optionally returns an object of any form:

Name	Description
`req`	A strongly-typed `NextApiRequest` object containing the typed body and query parameters of your request.
`res`	A strongly-typed `NextApiResponse` object that allows you to use only pre-defined status codes, `Content-Type` headers and response data formats from the current method handler.
`params`	The type of a combined object returned by both your Global middleware and Route middleware.

Error handlers

The error handler functions can be used for custom error handling. They support both asynchronous and synchronous execution.

// A global error handler, route error handler or method error handler.
errorHandler: ({ req, res, params }) => {
  // Your error handling logic.
};

Global error handler

The global error handler takes in an object with two attributes:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.

Route error handler

Route error handler can be used to override your global error handler. The route error handler takes in an object with three attributes:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.
`params`	The type of a combined object returned by both your Global middleware and Route middleware.

Method error handler

Method error handler can be used to override both your global error handler and route error handler. The method error handler takes in an object with three attributes and optionally returns an object of any form:

Name	Description
`req`	A strongly-typed `NextApiRequest` object containing the typed body and query parameters of your request.
`res`	A strongly-typed `NextApiResponse` object that allows you to use only pre-defined status codes, `Content-Type` headers and response data formats from the current method handler.
`params`	The type of a combined object returned by your Global middleware, Route middleware and Method middleware.

SwaggerUI config

The SwaggerUI config object can be used to customize the generated Swagger UI:

Name	Description
`title`	Custom page title meta tag value.
`description`	Custom page description meta tag value.
`logoHref`	An href for a custom logo.
`faviconHref`	An href for a custom favicon.