alexanderc / redirect

Decorator for handling Redirects with NestJS

Decorator for handling Redirects with NestJS

Installation

npm install @nestjsplus/redirect

Examples

NestJS doesn't currently have a decorator for doing redirects on route handlers. Here's how it looks with this decorator:

@Redirect({statusCode: HttpStatus.TEMPORARY_REDIRECT, url: 'https://nestjs.com'})
@Get('nest')
nest() {
  return;
}

Here's how it looks when the redirect response is determined dynamically:

@Redirect()
@Get('/somelocation')
index() {
  const url = this.getNewLocation();
  return { statusCode: HttpStatus.FOUND, url };
}

Sometimes you want to pass a response rather than redirecting:

@Redirect({ optionalRedirect: true })
@Get('/maybe-redirect')
index() {
  if (someOption) {
    return { hello: 'world' };
  }

  const url = this.getNewLocation();
  return { statusCode: HttpStatus.FOUND, url };
}

Motivation

To do a redirect with Nest out-of-the-box, you either need to utilize the platform-specific response (res) object, or write an interceptor. The former is pretty straightforward, though uses a non-Nest-like imperative style. It also puts you into manual response mode, meaning you can no longer rely on features like @Render(), @HttpCode() or interceptors that modify the response, and makes testing harder (you'll have to mock the response object, etc.).

Writing an interceptor isn't too bad, but wouldn't you rather just plug one in? ❤️ The @Redirect() decorator from this package wraps an interceptor in a declarative decorator that does this for you.

See Also

If you like this little gizmo, you may also be interested in the NestJS Cookie decorators.

Collectively, the @Redirect(), @Cookies(), @SignedCookies(), @SetCookies() and @ClearCookies() decorators in these packages provide a convenient set of features that make it easier to manage redirects and cookies in a standard and declarative way, minimize boilerplate code, and continue to use Nest features like @Headers(), @Render(), and other interceptors that mutate the response.

Importing the Decorator

Import the decorator, just as you would other Nest decorators, in the controllers that use it as shown below:

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';
import { Redirect } from '@nestjsplus/redirect';

@Controller()
export class AppController {
...

Static Redirects

For static redirects, where the statusCode and url (AKA location in the response headers) are known at compile time, simply specify them in the decorator:

@Redirect({statusCode: HttpStatus.TEMPORARY_REDIRECT, url: 'https://nestjs.com'})
@Get('nest')
nest {
  return;
}

Dynamic Redirects

For dynamic redirects, where the statusCode and/or url are computed in the route handler method, return an object from the method with the shape:

interface RedirectOptions {
  /**
   * URL to redirect to.
   */
  url: string;
  /**
   * HTTP Status Code to send.
   */
  statusCode: number;
}

For example:

@Redirect()
@Get('/somelocation')
index() {
  const url = this.getNewLocation();
  return { statusCode: HttpStatus.FOUND, url };
}

Recommendations

Utilize the HttpStatus enum from the @nestjs/common package to ensure you send the correct Http Status Codes, and to get convenient intellisense.

Restrictions

Express Only

This decorator currently only work with Nest applications running on @platform-express. Fastify support is not currently available.

Decorators Can't Access this

Note that decorators have access to the class (Controller), but not the instance. This means that, for example, if you want to pass a variable to a Redirect() decorator, you should pass a variable set in the outer scope of the file (e.g., a const above the controller class definition), as opposed to a property on the controller class.

Change Log

See Changelog for more information.

Contributing

Contributions welcome! See Contributing.

Author

• John Biundo (Y Prospect on Discord)

License

Licensed under the MIT License - see the LICENSE file for details.