Skip to main content

Nest 🆕

info

As part of @ts-rest/nest 3.26.0 we introduced the single-handler and multi-handler approach to Nest with ts-rest, for the legacy approach please see here.

The old API will likely be deprecated in 4.0.0, so we recommend using the new API although there is no rush to migrate.

Installation​

pnpm add @ts-rest/nest

Approaches​

Nest has always been a tricky framework to integrate with ts-rest, due to the way Nest handles routing and controllers. Nest normally uses large amounts of untyped decorators for each route, with ts-rest we introduce two new approaches to handle most of the heavy lifting for you.

Single Handler Approach - Easy Migration and Flexibility ⚡️​

We recommend the single handler approach as it provides a 1-1 migration strategy for legacy controllers. You can swap one Nest route for one ts-rest route without affecting other routes in a Controller.

import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
import { c } from './contract';

@Controller()
export class MyController {
  constructor(private readonly service: Service) {}

  @TsRestHandler(c.getPost)
  async getPost() {
    return tsRestHandler(c.getPost, async ({ params }) => {
      const post = await this.service.getPost(params.id);

      if (!post) {
        return { status: 404, body: null };
      }

      return { status: 200, body: post };
    });
  }

  @TsRestHandler(c.getPosts)
  async getPosts() {
    return tsRestHandler(c.getPosts, async () => {
      const posts = await this.service.getPosts();

      return { status: 200, body: posts };
    });
  }
}
note

Just like in regular Nest endpoints the names of the methods do not matter, you can name them whatever you like.

You may be wondering why do we return tsRestHandler from this method, all this function does is return the second argument. The only reason this exists is to provide you a fully typed implementation object which matches 1-1 with the way the @ts-rest/next, @ts-rest/express and @ts-rest/fastify packages work.

Benefits​

  • 1-1 migration strategy
  • Able to not have a one to one relationship between your contract and controllers
    • You are able to implement one ts-rest contract across multiple controllers based on your domain.

Multi Handler Approach - Ultimate Type Safety 🛡️​

The multi handler approach is fantastic for those of you who tend towards a more functional approach to your code, or if you want to ensure that your controller methods are always returning the correct response types.

import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
import { c } from './contract';

@Controller()
export class MyController {
  constructor(private readonly service: Service) {}

  @TsRestHandler(c)
  async handler() {
    return tsRestHandler(c, {
      getPost: async ({ params }) => {
        const post = await this.service.getPost(params.id);

        if (!post) {
          return { status: 404, body: null };
        }

        return { status: 200, body: post };
      },
      getPosts: async () => {
        const posts = await this.service.getPosts();

        return { status: 200, body: posts };
      },
    });
  }
}

The key difference here is you pass the entire contract (or a subset of a contract by defining a new contract or spreading multiple contracts) to the @TsRestHandler decorator and the tsRestHandler function.

caution

As of right now, for each route in a multi handler approach we instantiate the @All decorator for each route, this is potentially problematic if you have the same route in multiple contracts (with different methods), as it will cause a conflict.

We're looking into ways to solve this, but right now this may be a Nest limitation.

Benefits​

  • Less room for error, you are forced to implement all routes in a contract
  • Less boilerplate
  • Easier to move code between @ts-rest/next, @ts-rest/express and @ts-rest/fastify servers

Using Nest Decorators​

Despite using @TsRestHandler rather than @Get or @Post (etc.) you can still use all of the existing Nest decorators on your controller methods.

import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';

@Controller()
export class MyController {
  constructor(private readonly service: Service) {}

  @TsRestHandler(c.test)
  async myMethod(@Req() req: Request) {
    return tsRestHandler(c.test, async ({ params }) => {
      // ...

      console.log(req.headers);
      // ^ You can still use Nest decorators
    });
  }
}

In this example above we're using the @Req decorator to get access to the Request object, this is a great example of how you can use Nest decorators to get access to the underlying request/response objects.

This isn't limited to Param decorators, you can use any Nest decorator on your controllers as you would normally.

Throwing Type-Safe Errors 🍀​

Generally speaking you should try to return all errors as a response, so that you get the benefits of ts-rest typing in the contract (to let your consumers know what errors to expect).

However, sometimes it's much cleaner and simpler to throw an error rather than passing a response back to your handler - the problem is that you normally lose all type safety when you do this.

With TsRestException you can throw a Nest exception and it will be handled by the tsRestHandler function and returned as a fully typed response.

throw new TsRestException(contract.test, {
  status: 400,
  body: { code: 'UserAlreadySignedUp', message: 'User has already signed up' },
});

This example above will provide you autocomplete for the given status within the contract.test responses contract.

caution

The only risk of doing it this way is that you throw the wrong exception for a given route, which can happen if you throw from a piece of code used by multiple routes. If you want to be 100% sure you are throwing the correct exception you should use the tsRestHandler function to return the response.

This can be somewhat mitigated if you share the error code schema between multiple routes, so that you can't throw the wrong error code.

Configuration​

To configure ts-rest options you can use the @TsRest decorator on either your controller or use the existing @TsRestHandler decorator on your method. Controller options will be applied to all routes in the controller and will override any global options, and method options will override the controller options for that specific route.

Check out the configuration section for more details on the different configuration options, or on how to configure options globally.

import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';

@Controller()
@TsRest({ jsonQuery: true })
export class MyController {
  @TsRestHandler(c.getPost, { jsonQuery: false })
  async getPost() {
    return tsRestHandler(c.getPost, async () => {
      // ...
    });
  }
}

Gotchas​

caution

Currently any existing Nest global prefix, versioning, or controller prefixes will be ignored, please see https://github.com/ts-rest/ts-rest/issues/70 for more details.

If this feature is highly requested, we can investigate a solution.

We have added the ability to prefix paths, allowing more flexibility in defining your API endpoints. This can be used as a workaround for this functionality.