📄Overview
Harpy.js provides a flexible error handling system that allows you to customize error pages for different HTTP status codes (404, 500, 401, 403) with full support for JSX components and Tailwind CSS styling.
All error pages are automatically wrapped in an ErrorLayout component that ensures proper HTML structure and CSS imports, giving you beautiful styled error pages out of the box.
✨Default Error Pages
Harpy.js comes with beautifully designed default error pages that include:
- Gradient backgrounds with custom color schemes per error type
- Responsive design with Tailwind CSS
- Helpful error messages and actions
- Proper accessibility and SEO meta tags
- Error details display in development mode
Available Default Pages:
🎨Creating Custom Error Pages
Create custom error pages as JSX components that match your application's design. Your custom pages will automatically be wrapped in ErrorLayoutto include proper CSS styling.
Step 1: Create the Component
import React from 'react';import type { JsxLayoutProps } from '@harpy-js/core';import Logo from 'src/components/logo';export interface Custom404Props extends JsxLayoutProps { path?: string; message?: string;}export default function Custom404Page({ path, message = 'Page Not Found' }: Custom404Props) { return ( <div className="min-h-screen flex items-center justify-center px-6 py-12"> <div className="max-w-2xl w-full text-center"> {/* Logo */} <div className="mb-8"> <div className="inline-flex items-center justify-center w-24 h-24 bg-gradient-to-br from-purple-600 to-blue-600 rounded-full shadow-lg mb-4"> <Logo className="size-14 text-white" /> </div> </div> {/* Error Code */} <h1 className="text-9xl font-extrabold text-transparent bg-clip-text bg-gradient-to-r from-purple-600 to-blue-600 mb-4"> 404 </h1> {/* Message */} <h2 className="text-3xl font-bold text-gray-900 mb-4"> {message} </h2> <p className="text-lg text-gray-600 mb-8"> The page you're looking for doesn't exist. </p> {/* Action Button */} <a href="/" className="inline-block px-8 py-3 bg-gradient-to-r from-purple-600 to-blue-600 text-white font-semibold rounded-lg shadow-md hover:shadow-lg transform hover:-translate-y-0.5 transition-all duration-200" > Go to Homepage </a> </div> </div> );}Step 2: Define Props Interface
Your error page components should extend JsxLayoutPropsand can accept additional props:
import type { JsxLayoutProps } from '@harpy-js/core';export interface NotFoundPageProps extends JsxLayoutProps { message?: string; path?: string;}export interface ServerErrorPageProps extends JsxLayoutProps { message?: string; error?: string;}export interface UnauthorizedPageProps extends JsxLayoutProps { message?: string;}export interface ForbiddenPageProps extends JsxLayoutProps { message?: string;}⚙️Configuration
Configure custom error pages in your main.ts file using the setupHarpyApp function:
import { NestFactory } from '@nestjs/core';import { FastifyAdapter } from '@nestjs/platform-fastify';import { setupHarpyApp } from '@harpy-js/core';import DefaultLayout from './layouts/layout';import Custom404Page from './error-pages/404';import Custom500Page from './error-pages/500';async function bootstrap() { const app = await NestFactory.create( AppModule, new FastifyAdapter(), ); await setupHarpyApp(app, { layout: DefaultLayout, distDir: 'dist', publicDir: 'public', errorPages: { 404: Custom404Page, 500: Custom500Page, 401: Custom401Page, 403: Custom403Page, }, }); await app.listen({ port: 3000, host: '0.0.0.0' });}bootstrap();Pro Tip
You don't need to configure all error pages. Any status code without a custom page will automatically use the default Harpy.js error page for that status code.
🎁ErrorLayout Wrapper
The ErrorLayout component is automatically applied to all error pages (both default and custom). It ensures:
- Proper HTML structure with DOCTYPE, html, head, and body tags
- CSS links are included for Tailwind styling
- Responsive viewport meta tag
- Page title is set appropriately
ErrorLayout Implementation:
import React from 'react';interface ErrorLayoutProps { title?: string; children: React.ReactNode;}export default function ErrorLayout({ title = 'Error', children }: ErrorLayoutProps) { return ( <html lang="en"> <head> <meta charSet="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>{title}</title> {/* CSS imports for Tailwind styling */} <link rel="stylesheet" href="/styles/styles.css" /> </head> <body>{children}</body> </html> );}Automatic Wrapping
You don't need to manually wrap your error pages in ErrorLayout. The Harpy.js error handling system automatically applies this wrapper to all error pages, ensuring consistent styling and structure.
🎨Styling with Tailwind CSS
Error pages automatically receive Tailwind CSS styling through the ErrorLayout wrapper. You can use any Tailwind utility classes in your custom error pages:
Recommended Tailwind Patterns:
min-h-screen- Full viewport heightbg-gradient-to-br- Beautiful gradient backgroundsrounded-2xl shadow-2xl- Card-style containerstext-transparent bg-clip-text- Gradient text effectstransform hover:-translate-y-0.5- Interactive hover effects
Design Consistency
The default error pages use consistent design patterns that you can follow in your custom pages. Check the @harpy-js/core package for reference implementations.
⭐Best Practices
Keep Error Pages Simple
Error pages should load quickly and not depend on external resources that might fail. Keep them self-contained.
Provide Helpful Actions
Include links to common pages (home, docs, support) and actions (retry, go back) to help users recover from errors.
Show Error Details in Development
Use conditional rendering to show technical error details in development mode while keeping production pages user-friendly.
Match Your Brand
Customize error pages to match your application's design system, colors, and branding for a consistent user experience.
Test Your Error Pages
Visit invalid routes and test error scenarios to ensure your custom error pages render correctly with proper styling.