ElysiaJS error handler plugin for seamless integration with Next.js App Router.
pnpm add elysia-next-error-handlerUse createNextErrorHandler to configure the error handling pipeline. It handles Next.js internal errors (like redirects and 404s) correctly so they bubble up to Next.js.
// src/app/api/[[...slug]]/route.ts import { Elysia } from "elysia"; import { createNextErrorHandler, nextJsError, apiError, notFoundError, ignoreValidationAndParseError, internalServerError, APIError, } from "elysia-next-error-handler"; const app = new Elysia() .use( createNextErrorHandler([ // 1. Standard handlers // CRITICAL: Must be first. Checks for Next.js internal errors (like redirects and notFound()) // and re-throws them so Next.js can handle the control flow. nextJsError(), // Handles your custom APIError instances (e.g. throw new APIError("Bad Request", 400)) apiError(), // Converts Elysia's NotFoundError (404) into Next.js's notFound() notFoundError(), // Skip handling Elysia's validation and parse errors in this middleware, // allowing Elysia's default behavior (or other plugins) to handle them. ignoreValidationAndParseError(), // 2. Custom Logging (Optional) // You can inject custom logic here, like logging to Sentry or console. // Call `next()` to continue to the final error handler. ({ error, next }) => { console.error("Global Error Handler Caught:", error); // Sentry.captureException(error); return next(); }, // 3. Final Fallback // Catches any remaining errors (500s) and returns a generic JSON response: // { success: false, message: "Internal Server Error" } internalServerError(), ]) ) .get("/hello", () => "Hello Elysia"); export const GET = app.handle; export const POST = app.handle;Creates the plugin. Accepts an array of error handlers that are executed in order.
nextJsError(): Checks for Next.js internal errors (redirects,notFound()) and re-throws them so Next.js can handle them. Must be placed early in the chain.apiError(): CatchesAPIErrorinstances and returns a structured JSON response{ success: false, message, code }.notFoundError(): Catches Elysia'sNotFoundErrorand calls Next.jsnotFound().ignoreValidationAndParseError(): Ignores Elysia's validation and parse errors so they can be handled by other handlers or default behavior.internalServerError(): Logs the error and returns a generic 500 response.
A helper class for throwing operational errors with specific status codes and error codes.
new APIError(message: string, status?: number, code?: string)- message: The error message string.
- status: HTTP status code (default: 500).
- code: Optional error code string (e.g., 'UNAUTHORIZED', 'USER_NOT_FOUND').
1. Basic Usage (Bad Request)
throw new APIError("Invalid input parameters", 400, "INVALID_INPUT");2. Unauthorized Access (401)
// Throws a 401 Unauthorized error throw new APIError("You must be logged in to access this resource", 401, "UNAUTHORIZED");3. Resource Not Found (404)
// Throws a 404 Not Found error throw new APIError(`User with ID ${userId} not found`, 404, "USER_NOT_FOUND");When an APIError is thrown, the apiError() handler formats the response as:
{ "success": false, "message": "User with ID 123 not found", "code": "USER_NOT_FOUND" }