MFUI Error Pages

Standardized error page components for all Money Forward products, providing consistent error messaging and user experience with built-in internationalization and accessibility features.

• Changelog
• Official documentation (see README for usage examples)

Features

• 12 Predefined Error Types: Covers common 4xx and 5xx HTTP error scenarios
• Bilingual Support: Japanese and English content with professional tone
• Product Customization: Configurable contact links and guide pages
• Accessibility First: WCAG 2.2 Level A compliant with screen reader support
• Analytics Ready: Built-in callback support for tracking user interactions

Requirements

MFUI Error Pages requires the following libraries with minimum versions:

• React & React DOM: ≥18
• TypeScript: ≥5.1.0

Installation

1. Install the Package

Run the following command to install the package:

npm install @moneyforward/mfui-error-pages

2. Install the Peer Dependencies

This package requires react and react-dom with version 18 or above as peer dependencies.

npm install react react-dom

3. (Only Vite with SSR user) Add libraries to the noExternal dependencies

If you're using Vite with Server Side Rendering feature, you may need to add @moneyforward/mfui-error-pages to ssr.noExternal in your vite.config.ts to ensure proper bundling and dependency resolution.

export default defineConfig({
  // Other configurations
  ssr: {
    noExternal: [
      "@moneyforward/mfui-error-pages",
    ],
  },
});

Usage

Import Styles to Your Global Stylesheet

Add the following line into your global stylesheet (e.g. globals.css for Next.js application):

@import url('@moneyforward/mfui-error-pages/styles.css');

Basic Usage

import { ErrorMessage } from '@moneyforward/mfui-error-pages';

export function ErrorPage() {
  return (
    <ErrorMessage
      messageType="PAGE_NOT_FOUND"
      errorCode={404}
      guidePageUrl="https://your-product.example.com/help"
      contactEmail="[email protected]"
    />
  );
}

Message Types

Choose the appropriate messageType based on your error scenario:

Client Errors (4xx):

• PAID_PLAN_REQUIRED - User needs paid plan subscription
• SPECIFIC_PLAN_REQUIRED - User needs specific plan (use with planName prop)
• PERMISSION_DENIED_ACCOUNT - Permission error with account context
• PERMISSION_DENIED - Generic permission error
• LINK_EXPIRED - Expired authentication links
• PAGE_NOT_FOUND - 404 errors
• REQUEST_ERROR - Generic 400 errors

Server Errors (5xx):

• SCHEDULED_MAINTENANCE - Planned maintenance
• SERVER_BUSY - High traffic/load
• SYSTEM_ERROR - System failures
• EMERGENCY_MAINTENANCE - Unplanned maintenance
• UNEXPECTED_ERROR - Generic 500 errors

Business Logic Implementation

Your application determines which message to show based on error context:

function determineMessageType(errorCode: number, userContext: UserContext): MessageType {
  switch (errorCode) {
    case 401:
      return userContext.isExpired ? 'LINK_EXPIRED' : 'PERMISSION_DENIED';
    case 403:
      if (!userContext.isSubscribed) {
        return userContext.requiredPlan ? 'SPECIFIC_PLAN_REQUIRED' : 'PAID_PLAN_REQUIRED';
      }
      return 'PERMISSION_DENIED_ACCOUNT';
    case 404:
      return 'PAGE_NOT_FOUND';
    case 503:
      return isScheduledMaintenance() ? 'SCHEDULED_MAINTENANCE' : 'UNEXPECTED_ERROR';
    default:
      return errorCode >= 500 ? 'UNEXPECTED_ERROR' : 'REQUEST_ERROR';
  }
}

Advanced Usage

<ErrorMessage
  messageType="SPECIFIC_PLAN_REQUIRED"
  errorCode={403}
  language="en"
  planName="Professional Plan"
  guidePageUrl="https://product.example.com/en/upgrade"
  contactEmail="[email protected]"
  onActionClick={(action) => analytics.track('error_action_click', action)}
  navigationLinkType="back"
  DetailsSlot={(language) => (
    language === 'ja' ?
    'プラン詳細情報...' :
    'Plan details...'
  )}
/>

Reduce Bundle Size

For optimal bundle size, import components from their specific paths:

import { ErrorMessage } from '@moneyforward/mfui-error-pages/ErrorMessage';

Note: The package outputs ESM modules directly to dist/ without subdirectories for simplified consumption.

Props API

Required Props

| Prop | Type | Description | |------|------|-------------| | messageType | MessageType | Semantic error type (see Message Types section) | | errorCode | number | HTTP status code (400-599) |

Optional Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | language | 'ja' \| 'en' | 'ja' | Language for error messages | | planName | string | - | Required plan name (for SPECIFIC_PLAN_REQUIRED) | | guidePageUrl | string | - | Product-specific guide page URL | | contactEmail | string | - | Product-specific support email | | hideContactGuide | boolean | false | Hide guide action links | | hideNavigationLink | boolean | false | Hide navigation link | | navigationLinkType | 'top' \| 'back' | 'top' | Navigation link type | | navigationLinkLabel | string | - | Custom label for navigation link | | navigationLinkUrl | string | '/' | Custom URL for navigation link | | onActionClick | (action: ActionLink) => void | - | Analytics callback for link clicks | | DetailsSlot | ReactNode \| ((language) => ReactNode) | - | Custom details section | | className | string | - | Additional CSS classes |

TypeScript Types

import type { MessageType, ErrorMessageProps } from '@moneyforward/mfui-error-pages';

Product Integration

Required Configuration

Each Money Forward product must provide:

1. Guide Page URL: Link to product-specific help documentation
2. Contact Email: Product support email address

// Example for a Money Forward product
const PRODUCT_CONFIG = {
  guidePageUrl: 'https://biz.moneyforward.com/help',
  contactEmail: '[email protected]'
};

<ErrorMessage
  messageType={messageType}
  errorCode={errorCode}
  guidePageUrl={PRODUCT_CONFIG.guidePageUrl}
  contactEmail={PRODUCT_CONFIG.contactEmail}
/>

Migration from Custom Error Pages

1. Audit existing error pages to map them to the 12 predefined message types
2. Implement error type determination logic based on HTTP status codes and user context
3. Replace error page components gradually, route by route
4. Configure product-specific URLs for guide pages and contact information
5. Add analytics tracking using the onActionClick callback

Getting Help

Documentation

• Official documentation: See README for usage examples and component API
• Architecture Documentation: Technical implementation details
• ADR: Architectural decisions and design rationale

All company names, product and service names, and logos are trademarks or registered trademarks of their respective owners.