Next.js API routes – Global Error Handling and Clean Code Practices

npx create-next-app@latest --ts
# or
yarn create next-app --ts

npm i yup http-errors && npm i --dev @types/http-errors
# or
yarn add yup http-errors && yarn add --dev @types/http-errors

// ./utils/api.ts
import createHttpError from "http-errors";

import { NextApiHandler, NextApiRequest, NextApiResponse } from "next";
import { Method } from "axios";

// Shape of the response when an error is thrown
interface ErrorResponse {
  error: {
    message: string;
    err?: any; // Sent for unhandled errors reulting in 500
  };
  status?: number; // Sent for unhandled errors reulting in 500
}

type ApiMethodHandlers = {
  [key in Uppercase<Method>]?: NextApiHandler;
};

export function apiHandler(handler: ApiMethodHandlers) {
  return async (req: NextApiRequest, res: NextApiResponse<ErrorResponse>) => {
    try {
      const method = req.method
        ? (req.method.toUpperCase() as keyof ApiMethodHandlers)
        : undefined;

      // check if handler supports current HTTP method
      if (!method)
        throw new createHttpError.MethodNotAllowed(
          `No method specified on path ${req.url}!`
        );

      const methodHandler = handler[method];
      if (!methodHandler)
        throw new createHttpError.MethodNotAllowed(
          `Method ${req.method} Not Allowed on path ${req.url}!`
        );

      // call method handler
      await methodHandler(req, res);
    } catch (err) {
      // global error handler
      errorHandler(err, res);
    }
  };
}

export type Method =
  |'GET'
  |'DELETE'
  |'HEAD'
  |'OPTIONS'
  |'POST'
  |'PUT'
  |'PATCH'
  |'PURGE'
  |'LINK'
  |'UNLINK';

// ./utils/api.ts

import { ValidationError } from "yup";



function errorHandler(err: unknown, res: NextApiResponse<ErrorResponse>) {
  // Errors with statusCode >= 500 are should not be exposed
  if (createHttpError.isHttpError(err) && err.expose) {
    // Handle all errors thrown by http-errors module
    return res.status(err.statusCode).json({ error: { message: err.message } });
  } else if (err instanceof ValidationError) {
    // Handle yup validation errors
    return res.status(400).json({ error: { message: err.errors.join(", ") } });
  } else {
    // default to 500 server error
    console.error(err);
    return res.status(500).json({
      error: { message: "Internal Server Error", err: err },
      status: createHttpError.isHttpError(err) ? err.statusCode : 500,
    });
  }
}

// ./pages/api/article.ts
import createHttpError from "http-errors";
import * as Yup from "yup";

import { NextApiHandler } from "next";

import { apiHandler } from "utils/api";
import { validateRequest } from "utils/yup";

// Fake DB to demonstrate the API
const BLOG_DB = [
  {
    id: 1,
    title: "Top 10 anime betrayals",
    content: "Lorem ipsum dolor sit amet ....",
    publishedTimestamp: 1665821111000,
  },
];

type GetResponse = {
  data: typeof BLOG_DB | typeof BLOG_DB[number];
};

/**
 * returns all articles or the article with the given id if query string is provided
 */
const getArticle: NextApiHandler<GetResponse> = async (req, res) => {
  const { id } = req.query;
  if (id) {
    // find and return article with given id
    const article = BLOG_DB.find((article) => article.id === Number(id));

    if (!article)
      throw new createHttpError.NotFound(`Article with id ${id} not found!`);
    // OR
    // if (!article) throw new createHttpError[404](`Article with id ${id} not found!`)
    res.status(200).json({ data: article });
  } else {
    res.status(200).json({ data: BLOG_DB });
  }
};

type PostResponse = {
  data: typeof BLOG_DB[number];
  message: string;
};

const postArticleSchema = Yup.object().shape({
  title: Yup.string().required("Title is required!"),
  content: Yup.string()
    .required("Content is required!")
    .max(
      5000,
      ({ max }) => `Character limit exceeded! Max ${max} characters allowed!`
    ),
  publishedTimestamp: Yup.number()
    .required("Published timestamp is required!")
    .lessThan(Date.now(), "Published timestamp cannot be in the future!"),
});

const createArticle: NextApiHandler<PostResponse> = async (req, res) => {
  const data = validateRequest(req.body, postArticleSchema);
  const newArticle = { ...data, id: BLOG_DB.length + 1 };
  BLOG_DB.push(newArticle);

  res
    .status(201)
    .json({ data: newArticle, message: "Article created successfully!" });
};

type DeleteResponse = {
  data: typeof BLOG_DB[number];
  message: string;
};

const deleteArticleById: NextApiHandler<DeleteResponse> = async (req, res) => {
  const { id } = req.query;

  if (!id) throw new createHttpError.BadRequest("Article id is required!");

  const articleIndex = BLOG_DB.findIndex(
    (article) => article.id === Number(id)
  );

  if (articleIndex < 0)
    throw new createHttpError.NotFound(`Article with id ${id} not found!`);

  BLOG_DB.splice(articleIndex, 1);

  res.status(200).json({
    data: BLOG_DB[articleIndex],
    message: "Article deleted successfully!",
  });
};

export default apiHandler({
  GET: getArticle,
  POST: createArticle,
  DELETE: deleteArticleById,
});

// ./utils/yup.ts

import { ObjectSchema } from "yup";
import { ObjectShape } from "yup/lib/object";

export function validateRequest<T extends ObjectShape>(
  data: unknown,
  schema: ObjectSchema<T>
) {
  const _data = schema.validateSync(data, {
    abortEarly: false,
    strict: true,
  });
  return _data;
}