Errors

Reusable error handling components for the NJ Municipality Lookup application. Provides consistent error UI, theme support, and internationalization for all err

Error Components

Reusable error handling components for the NJ Municipality Lookup application. Provides consistent error UI, theme support, and internationalization for all error states.

Components

ErrorPage

Reusable error page component that displays error messages with actions.

File: error-page.tsx

Features:

• Theme-aware styling (light/dark mode)
• Customizable icon, heading, message, and suggestion
• Primary and secondary action buttons
• Responsive design
• Accessible markup

Usage:

import { ErrorPage } from "@/components/errors/error-page";
import { AlertCircle } from "lucide-react";

<ErrorPage
  icon={<AlertCircle className="w-16 h-16" />}
  heading="Page Not Found"
  message="The page you're looking for doesn't exist."
  suggestion="Try checking the URL for typos."
  primaryAction={{ label: "Go Home", href: "/" }}
  secondaryAction={{ label: "Contact Support", href: "/support" }}
/>;

Props:

• icon: ReactNode - Icon to display (typically AlertCircle from lucide-react)
• heading: string - Main error heading
• message: string - Error description
• suggestion?: string - Optional suggestion text
• primaryAction: Action - Primary button (href or onClick)
• secondaryAction?: Action - Optional secondary button

PageErrorBoundary

React Error Boundary for catching component-level errors.

File: page-error-boundary.tsx

Features:

• Catches errors in child component tree
• Displays fallback UI using ErrorPage
• Provides reset functionality
• Logs errors to console
• Can be used at page or component level

Usage:

import { PageErrorBoundary } from "@/components/errors/page-error-boundary";

// Wrap page content
export default function Page() {
  return (
    <PageErrorBoundary>
      <PageContent />
    </PageErrorBoundary>
  );
}

// Wrap specific section
<PageErrorBoundary>
  <ComplexComponent />
</PageErrorBoundary>;

Error Catching:

• ✅ Errors during render
• ✅ Errors in lifecycle methods
• ✅ Errors in constructors
• ❌ Event handler errors (use try/catch)
• ❌ Async code errors (use try/catch)
• ❌ Server-side rendering errors

Error Pages

not-found.tsx (404)

Custom 404 page for non-existent routes.

File: src/app/not-found.tsx

Features:

• Inherits root layout (header, nav, footer)
• Uses next-intl translations
• Links to home and lookup pages
• Automatically triggered by Next.js for 404 errors

error.tsx (General Errors)

Error page for client-side errors in pages and layouts.

File: src/app/error.tsx

Features:

• Inherits root layout
• Catches errors in page components
• Provides reset functionality
• Uses next-intl translations
• Logs errors to console

global-error.tsx (500 Errors)

Error page for critical root layout and server errors.

File: src/app/global-error.tsx

Features:

• Renders own HTML structure (no layout inheritance)
• Catches errors in root layout
• Minimal header with app branding
• Theme and i18n support
• Logs critical errors

Translations

All error text is defined in src/locales/en.json under the errors namespace:

{
  "errors": {
    "notFound": {
      "heading": "Page Not Found",
      "message": "...",
      ...
    },
    "general": { ... },
    "serverError": { ... }
  }
}

Styling

Error components use Tailwind classes matching the application's design system:

• Backgrounds: bg-white dark:bg-ocean-950
• Text: text-gray-900 dark:text-zinc-100
• Muted text: text-gray-600 dark:text-zinc-400
• Primary button: bg-primary-600 hover:bg-primary-700 dark:bg-primary-500
• Secondary button: bg-white dark:bg-ocean-800 border border-gray-300 dark:border-ocean-700
• Error icon: text-error

Error Hierarchy

Next.js error handling follows this hierarchy:

1. global-error.tsx - Catches errors in root layout and server components
2. error.tsx - Catches errors in pages and nested layouts
3. not-found.tsx - Handles 404 errors for non-existent routes
4. PageErrorBoundary - Optional component-level error catching

Testing Error Pages

Test 404 Page

Navigate to a non-existent route:

http://localhost:3000/non-existent-page

Test Error Page

Trigger an error in a page component:

export default function TestPage() {
  throw new Error("Test error");
}

Test Global Error

Trigger an error in root layout (production only):

// In src/app/layout.tsx
throw new Error("Layout error");

Note: In development, Next.js shows its own error overlay. Test production error pages using:

bun run build
bun run start

Accessibility

All error components follow accessibility best practices:

• Semantic HTML (<h1>, <p>, <button>, <a>)
• Proper heading hierarchy
• Keyboard navigation support
• Focus management on action buttons
• ARIA attributes where needed
• Sufficient color contrast (WCAG AA)

Best Practices

1. Use Next.js error files for page-level errors (error.tsx, not-found.tsx)
2. Use PageErrorBoundary sparingly - only wrap complex components prone to errors
3. Log errors to monitoring service (Sentry, CloudWatch, etc.)
4. Provide clear actions - always give users a way to recover
5. Test error states in both light and dark modes
6. Keep error messages user-friendly - avoid technical jargon
7. Use translations for all error text to support internationalization

Future Enhancements

Potential improvements for error handling:

• Integrate error tracking service (Sentry)
• Add error reporting form for users
• Track error frequency and patterns
• Add error recovery suggestions based on error type
• Implement offline error handling
• Add error state animations
• Create error-specific metadata (OG tags)