nextjs-exception-middleware

This middleware allows you to throw exceptions in your route handlers that are caught and returned as JSON.

For example,

// Inside a route handler
if (bad_soups.includes(soup_param)) {
  throw new BadRequestException({
    type: "cant_make_soup",
    message: "Soup was too difficult, please specify a different soup",
    data: { soup_param }
  })
}

will be returned as

{
  "error": {
    "type": "cant_make_soup",
    "message": "Soup was too difficult, please specify a different soup",
    "data": {
      "soup_param": "tomato"
    }
  }
}

with a status code of 400.

Installation

yarn add nextjs-exception-middleware or npm install nextjs-exception-middleware -s

Usage

Wrap your API handlers like so:

import { withExceptionHandling } from "nextjs-exception-middleware"

export default withExceptionHandling({
  // all parameters are optional
  addOkStatus: false // add top-level "ok" status key to JSON responses
  okStatusOptions: {
    addIf: (req) => req.method === "GET" // only add "ok" status key if request is GET
  },
  exceptionHandlingOptions: {
    getErrorContext: (req, errorContext) => {
      // add any additional context to returned errors
      errorContext.request_id = req.requestId
      // delete error stack
      delete errorContext.stack
      return errorContext
    }
  }
})(async (req, res) => {
  // ...
})

Exception Types

HttpException

Use HttpException to throw any HTTP exception providing the appropriate status code.

import { HttpException } from "nextjs-exception-middleware"

export default (req, res) => {
  /* ... */
  throw new HttpException(403, {
    type: "access_forbidden",
    message: "No rights to access the content",
    data: { client_id }
  })
} 

BadRequestException

Use BadRequestException to respond with 400 Bad Request status code.

import { BadRequestException } from "nextjs-exception-middleware"

export default (req, res) => {
  /* ... */
  throw new BadRequestException({
    type: "bad_request",
    message: "Request cannot be processed due to malformed request syntax"
  })
} 

UnauthorizedException

Use UnauthorizedException to respond with 401 Unauthorized status code.

import { UnauthorizedException } from "nextjs-exception-middleware"

export default (req, res) => {
  /* ... */
  throw new UnauthorizedException({
    type: "unauthorized",
    message: "Authenticate yourself to get the requested response",
    data: { client_id }
  })
} 

NotFoundException

Use NotFoundException to respond with 404 Not Found status code.

import { NotFoundException } from "nextjs-exception-middleware"

export default (req, res) => {
  /* ... */
  throw new NotFoundException({
    type: "not_found",
    message: "The requested resource not found",
    data: { resource_id }
  })
} 

MethodNotAllowedException

Use MethodNotAllowedException to respond with 405 Method Not Allowed status code.

import { MethodNotAllowedException } from "nextjs-exception-middleware"

export default (req, res) => {
  /* ... */
  throw new MethodNotAllowedException({
    type: "method_not_allowed",
    message: "Request method ${req.method} is not allowed"
  })
} 

InternalServerErrorException

Use InternalServerErrorException to respond with 500 Internal Server Error status code.

import { InternalServerErrorException } from "nextjs-exception-middleware"

export default (req, res) => {
  /* ... */
  throw new InternalServerErrorException({
    type: "server_error",
    message: "Internal server error occurred"
  })
}