Comprehensive Error Handling

Front-Commerce provides a robust error handling system that allows you to gracefully manage errors at different levels of your application. This guide will walk you through the process of implementing error boundaries and customizing error pages to enhance your application's resilience and user experience.

Understanding Error Boundaries

Error boundaries in Front-Commerce are based on Remix's error handling mechanism. They allow you to catch JavaScript errors anywhere in their child component tree, log those errors, and display a fallback UI instead of the component tree that crashed.

Front-Commerce offers three main types of error boundaries:

1. Root Error Boundary
2. Layout Error Boundary
3. Route-specific Error Boundary

Root Error Boundary

The Root Error Boundary is the top-level error handler for your entire application. It's typically defined in your app/root.tsx file.

To implement the Root Error Boundary:

1. Import the RootErrorBoundary component from Front-Commerce's theme:

   import { RootErrorBoundary } from "theme/pages/Error";

2. Add the ErrorBoundary export to your root.tsx:

   export const ErrorBoundary = RootErrorBoundary;

This will catch any unhandled errors in your application and display a generic error page.

note

The RootErrorBoundary is wrapped in the SimpleLayout component.

Layout Error Boundary

For routes that use a custom layout, you can implement a Layout Error Boundary. This allows you to maintain your layout structure even when an error occurs.

Here is an example of how we use the LayoutErrorBoundary for the _main.tsx layout:

1. Import the LayoutErrorBoundary component:

   app/routes/_main.tsx

   import { LayoutErrorBoundary } from "theme/pages/Error";

2. Use it within your layout component's ErrorBoundary:

   app/routes/_main.tsx

   export function ErrorBoundary() {
     // If this loader fails, it will be caught by the RootErrorBoundary
     const data = useRouteLoaderData<typeof loader>("routes/_main");
     const { headerNavigationMenu = [], footerNavigationMenu = [] } =
       data || {};
   
     return (
       <Layout
         headerNavigationMenu={headerNavigationMenu}
         footerNavigationMenu={footerNavigationMenu}
       >
         <LayoutErrorBoundary />
       </Layout>
     );
   }

This approach ensures that your layout remains intact while displaying the error message.

note

The LayoutErrorBoundary is not wrapped in any layout as this is meant to be used inside a route which is already wrapped in a layout.

Customizing Error Pages

Front-Commerce allows you to customize error pages for specific HTTP status codes. This is done through the RouteResponseError component and the appErrorPages object.

Adding Custom Error Pages

1. Create a new component for your custom error page, e.g., CustomNotFound.tsx.

2. Add your custom error page to the appErrorPages object in theme/pages/Error/appErrorPages.ts:

   theme/pages/Error/appErrorPages.ts

   import CustomNotFound from "./CustomNotFound";
   
   export const appErrorPages = {
     404: CustomNotFound,
   } satisfies AppErrorPages;

3. The RouteResponseError component will now use your custom component for 404 errors.

Default Error Pages

Front-Commerce provides default error pages for common status codes:

• 429: Rate Limit Exceeded
• 503: Maintenance
• 404: Not Found

You can override these by adding your own components to the theme/pages/Error/appErrorPages.ts object.

Customizing Meta Tags

Since version 3.9

To extend the meta tags for your route error pages, you can register new meta tags in the root-error-meta feature.

Adding Custom Meta Tags

You can refer to the example demo extension for implementation details.

example-extension/application-extension/index.ts

hooks.registerFeature("root-error-meta", {
   // ...
   unstable_lifecycleHooks: {
      onFeaturesInit: (hooks) => {
         hooks.registerFeature("root-error-meta", {
            config: {
               messages: () => {
                  return (intl: IntlShape) => {
                     "500": {
                        // with intl translations
                        title: intl.formatMessage({ id: "500.title" }),
                        description: intl.formatMessage({ id: "500.description" }),
                     },
                     "418": {
                        // without intl translations
                        title: "Custom - Teapot",
                        description: "I'm a teapot",
                     },
                  };
               },
            },
         });
      },
   },
});

Default Meta Tags

Front-Commerce provides default meta tags for common status codes: (see exhaustive list in root-error-meta.ts)

• 429: Rate Limit Exceeded
• 503: Maintenance
• 404: Not Found

Best Practices

1. Granular Error Handling: Use route-specific error boundaries for handling errors that are unique to certain parts of your application.
2. Informative Error Messages: Provide clear and helpful error messages to guide users on what went wrong and what they can do next.
3. Logging: Implement proper error logging to help with debugging and monitoring application health.
4. Graceful Degradation: Design your error pages to maintain as much functionality as possible, allowing users to navigate away from the error or retry their action.
5. Consistency: Maintain a consistent look and feel in your error pages to align with your application's overall design.

By following these guidelines and utilizing Front-Commerce's error handling components, you can create a robust and user-friendly error management system for your e-commerce application.