Skip to main content

Next.js Server

Installation​

pnpm add @ts-rest/next

Usage​

For maximum type safety, by default @ts-rest/next uses a single endpoint for all routes.

info

It is possible to split out to multiple endpoints by having multiple [...ts-rest].tsx files in different folders, so long as the routers you use all begin with the same path e.g. all /posts endpoints in a posts folder.

// pages/api/[...ts-rest].tsx
import { createNextRoute, createNextRouter } from '@ts-rest/next';

const postsRouter = createNextRoute(api.posts, {
  createPost: async (args) => {
    const newPost = await posts.createPost(args.body);

    return {
      status: 201,
      body: newPost,
    };
  },
});

const router = createNextRoute(api, {
  posts: postsRouter,
});

// Actually initiate the collective endpoints
export default createNextRouter(api, router);

createNextRouter is a function that takes a router and a complete router, and creates endpoints, with the correct methods, paths and callbacks.

JSON Query Parameters​

To handle JSON query parameters, you can use the jsonQuery option.

export default createNextRouter(api, router, { jsonQuery: true });

Response Validation​

To enable response parsing and validation, you can use the validateResponses option. If there is a corresponding response Zod schema defined in the contract for the returned status code, the response will be parsed and validated. If validation fails a ResponseValidationError will be thrown causing a 500 response to be returned.

export default createNextRouter(api, router, { validateResponses: true });

Error Handling​

You can create a global error handler to handle any thrown errors by using the errorHandler option. This includes response validation errors.

export default createNextRouter(api, router, {
  responseValidation: true,
  errorHandler: (error: unknown, req: NextApiRequest, res: NextApiResponse) => {
    if (error instanceof ResponseValidationError) {
      console.log(error.cause);
      return res.status(500).json({ message: 'Internal Server Error' });
    }
  },
});

Future Work​

As this pattern doesn't support a lambda per endpoint, it is planned to provide a helper utility to allow individual endpoints to be created.

The downside of this is that it will not be possible to give a Typescript warning if the path is incorrect.