Handling Error Pages (404)

Learn how to personalize the 404 error page and manually trigger error responses from your components or API routes.

Overview

A well-designed error page is essential for a good user experience. JopiJS makes it easy to create custom branded pages for the most common HTTP errors.

In this guide, you will learn:

How to personalize the 404 Not Found page.
How to manually trigger error pages from a React component.
How to return error codes from API routes.
How to handle other errors like 500, 401, and 400.

1. Personalizing the 404 Page

By default, JopiJS provides a simple 404 page. To replace it with your own design, simply create a route named error404 inside any of your modules.

Structure:

src/
└── mod_theme/
    └── @routes/
        └── error404/         # Special route name
            └── page.tsx      # Your custom error design

Example Implementation:

src/mod_theme/@routes/error404/page.tsx

import { usePageTitle } from "jopijs/ui";

export default function NotFoundPage() {
    usePageTitle("Page Not Found");

    return (
        <div className="flex flex-col items-center justify-center min-h-screen">
            <h1 className="text-4xl font-bold">404</h1>
            <p className="mt-4 text-gray-600">Oops! The page you are looking for doesn't exist.</p>
            <a href="/" className="mt-6 text-blue-500 hover:underline">Return Home</a>
        </div>
    );
}

2. Manually Triggering Errors

There are times when a URL is technically valid, but the content doesn't exist (e.g., a product ID that isn't in your database). In these cases, you need to manually trigger an error.

From a React Page

Use the helper functions from @/routes to swap the current view for an error page.

src/mod_shop/@routes/products/[id]/page.tsx

import { error404 } from "@/routes";
import { JopiPageProps } from "jopijs/ui";

export default function ProductPage(props: JopiPageProps) {
    const product = getProduct(props.params.id);

    if (!product) {
        // This will render your custom error404 page
        return error404();
    }

    return <div>Product: {product.name}</div>;
}

From an API Route

API routes return raw HTTP responses. Use the dedicated methods on the request object.

src/mod_api/@routes/data/onGET.ts

import { JopiRequest } from "jopijs";

export default function(req: JopiRequest) {
    if (!req.req_urlInfos.searchParams.get("id")) {
        return req.res_returnError404_NotFound();
    }

    return req.res_jsonResponse({ data: "..." });
}

3. Other Error Types (500, 401, 400)

JopiJS follows the same logic for other common HTTP errors. You can personalize them by creating the corresponding routes in @routes.

Error Code	Route Name	Helper (Page)	Method (API)
404	`error404`	`error404()`	`res_returnError404_NotFound()`
500	`error500`	`error500()`	`res_returnError500_ServerError()`
401	`error401`	`error401()`	`res_returnError401_Unauthorized()`
400	N/A*	N/A	`res_returnError400_BadRequest()`

Why no error400 page?
The 400 Bad Request error is typically used by APIs to signal invalid input data. Since it's a technical error usually triggered by programmatic calls (like AJAX), it doesn't typically require a user-facing visual template.

Handling Server Failures (500)

If your code throws an uncaught exception, JopiJS will automatically try to display your error500 page.

src/mod_theme/@routes/error500/page.tsx

export default function ServerErrorPage() {
    return (
        <div>
            <h1>Something went wrong</h1>
            <p>Our team has been notified. Please try again later.</p>
        </div>
    );
}