📦 NextFastAPI — Lightweight API Controller for Next.js (App Router)

NextFastAPI provides an easy way to create structured API routes in Next.js App Router, with Express-like middleware support, multi-method handlers, built-in error handling, and strong typing.

🚀 Installation

npm install nextfastapi
# or
yarn add nextfastapi

📄 Quick Start

1. Create a simple GET router

// app/api/hello/route.ts

import { RouteController } from "nextfastapi";

const controller = new RouteController();

controller.get(async (req) => {
  return Response.json({ message: "Hello from NextFastAPI!" });
});

export const GET = controller.expose();

⚙️ Middlewares

Middlewares let you run logic before your handlers. You can apply middlewares globally (all methods) or per method.

2. Global Middleware (for all methods)

import type { Middleware } from "nextfastapi/types";

type Context = {
  requestTime?: string;
};

const controller = new RouteController<Context>();

const addRequestTime: Middleware<Context> = (req, params, next) => {
  req.context.requestTime = new Date().toISOString();
  return next();
};

controller.use(addRequestTime);

controller.get((req) => {
  const requestTime = req.context.requestTime;

  return Response.json({ message: `GET Method: ${requestTime}` });
});

controller.post((req) => {
  const requestTime = req.context.requestTime;

  return Response.json({ message: `GET Method: ${requestTime}` });
});

export const GET = controller.expose();
export const POST = controller.expose();

3. Middleware for a Single Method

import type { Middleware } from "nextfastapi/types";

// Session Control Middleware
import { insertUserRole } from "./middlewares";

type Context = {
  userRole?: "admin" | "user";
};

const controller = new RouteController<Context>();

const checkAdmin: Middleware<Context> = (req, params, next) => {
  if (req.context.userRole !== "admin") {
    throw new ForbiddenError({ message: "You are not ADMIN!" });
  }
  return next();
};

// Inserting Admin Verification Middleware
controller.get(insertUserRole, checkAdmin, (req) => {
  return Response.json({ secret: "This is admin only" });
});

controller.post((req) => {
  return Response.json({ secret: "This secret is PUBLIC" });
});

export const GET = controller.expose();
export const POST = controller.expose();

⚠️ Error Handling

NextFastAPI comes with a built-in error manager that formats errors automatically.

4. Using Built-in HTTP Errors

controller.get((req) => {
  throw new BadRequestError({ message: "Custom Bad Request Error Message" });
});

export const GET = controller.expose();
export const POST = controller.expose();

5. Custom Error Handler (optional)

import { transformError } from "nextfastapi/errors";

controller.onError((err, req) => {
  // parse js built in error for a base object
  const safeError = transformError(err);

  const response = {
    error: safeError.message,
    action: safeError.action, // default action message added by error classes
  };

  return Response.json(response, {
    status: safeError.statusCode,
  });
});

📚 Available HTTP Error Classes

| Error Class | HTTP Status Code | Default Action Message | | -------------------------- | ---------------- | --------------------------------------------------- | | BadRequestError | 400 | "Check the request data and try again." | | UnauthorizedError | 401 | "Provide valid authentication credentials." | | ForbiddenError | 403 | "Ensure you have permission to access this." | | NotFoundError | 404 | "Verify the resource identifier and try again." | | MethodNotAllowedError | 405 | "Use a supported HTTP method for this endpoint." | | ConflictError | 409 | "Resolve conflicting data before retrying." | | UnprocessableEntityError | 422 | "Check the entity's data validity and constraints." | | TooManyRequestsError | 429 | "Reduce request frequency or wait before retrying." | | InternalError | 500 | "Try again later or contact support." |

💡 Summary

• Create routes with .get(), .post(), etc., and export with <controller>.expose().
• Add middlewares globally with .use() or per method by passing them as arguments.
• Use built-in HTTP error classes for standardized errors.
• Customize error responses with .onError() if you want.
• req.context allows sharing data between middlewares and handlers.

📄 License

MIT © 2025 – Developed by Ezequias Lopes