Erro handling for renderização do módulo remoto em Module Federation.

Background

Remote módulo processo de carregamento may fail due para network recurso carregamento falha ou business logic renderização falha.

Though Module Federation Runtime fornece detailed informações detalhadas de log de erro e runtime hook para help users locate o cause de carregamento falha, precisamos add erro fallback mechanism para garantir o stability do entire site, preventing o entire site de crashing due para o falha de uma renderização do módulo remoto.

Solution

To build uma robust carregamento de módulo remoto mechanism, nós pode handle possíveis problemas do seguintes three levels:

O seguinte solutions pode refer para o exemplos em router-demo.

Network layer: Retry mechanism

Use @module-federation/retry-plugin plugin para tratar problemas relacionados à rede:

Automatically retry falhou recurso requests
Configurable retry times e interval
Suporte custom tratamento de erros estratégia

Carregamento layer: Erro handling hook

Use Module Federation Runtime fornecido errorLoadRemote hook para mais granular tratamento de erros:

Capture erros em diferente carregamento lifecycle
Forneçum componente de fallback ou backup recurso
Suporte custom tratamento de erros estratégia

Rendering layer: Erro boundary

Use React's ErrorBoundary mechanism para tratar componente renderização exceptions:

Graceful degradation, display friendly erro prompts
Isolate erro impact, prevent o entire aplicação de crashing
Suporte erro recovery e retry carregamento

Esses three solutions são for diferente scenarios, pode ser usado separadamente, ou combined para forneça uma mais comprehensive tratamento de erros mechanism. Below nós vai introduce o specific implementation de each solution em detail.

Add mecanismo de retry

For weak network environment ou producer has não started o service, nós pode add mecanismo de retry para solicitar recursos multiple times, que vai increase o probability de recurso carregamento success.

Module Federation official fornece retry plugin @module-federation/retry-plugin para suporte mecanismo de retry for recursos, oferece retry para recursos fetch e script.

Registro em runtime puro


import React from 'react';
import { createInstance, loadRemote } from '@module-federation/enhanced/runtime';
import { RetryPlugin } from '@module-federation/retry-plugin';

const mf = createInstance({
  name: 'host',
  remotes: [
      {
          name: "remote1",
          alias: "remote1"
          entry: "http://localhost:2001/mf-manifest.json",
      }
  ],
  plugins: [
    RetryPlugin({
      retryTimes: 3,
      retryDelay: 1000,
      manifestDomains: ['https://domain1.example.com', 'https://domain2.example.com'],
      domains: ['https://cdn1.example.com', 'https://cdn2.example.com'],
      addQuery: ({ times, originalQuery }) => `${originalQuery}&retry=${times}`,
      onRetry: ({ times, url }) => console.log('retry', times, url),
      onSuccess: ({ url }) => console.log('success', url),
      onError: ({ url }) => console.log('error', url),
    }),
  ]
});

// Module loading
const Remote1Button = React.lazy(() => mf.loadRemote('remote1/button'));

export default () => {
  return (
    <React.Suspense fallback={<div> Loading Remote1App...</div>}>
      <Remote1Button />
    </React.Suspense>
  );
}

// Method/function loading
mf.loadRemote<{add: (...args: Array<number>)=> number }>("remote1/util").then((md)=>{
    md.add(1,2,3);
});

Para saber mais sobre a configuração de parâmetros de @module-federation/retry-plugin consulte document

Plugin registration

import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'host',
      runtimePlugins: [
        path.join(__dirname, './src/runtime-plugin/retry.ts'),
      ],
    }),
  ],
});

// src/runtime-plugin/retry.ts
import { RetryPlugin } from '@module-federation/retry-plugin';

const retryPlugin = () =>
  RetryPlugin({
    retryTimes: 3,
    retryDelay: 1000,
    manifestDomains: ['https://domain1.example.com', 'https://domain2.example.com'],
    domains: ['https://cdn1.example.com', 'https://cdn2.example.com'],
    addQuery: ({ times, originalQuery }) => `${originalQuery}&retry=${times}`,
    onRetry: ({ times, url }) => console.log('retry', times, url),
    onSuccess: ({ url }) => console.log('success', url),
    onError: ({ url }) => console.log('error', url),
  });
export default retryPlugin;

Effect as follows:

Block network request

Block then Habilite

errorLoadRemote hook

Para erros no processo de carregamento de módulos remotos, eles podem ser captured no errorLoadRemote hook.

errorLoadRemote é o hook for tratamento de erros em Module Federation Runtime. Quando o carregamento de módulo remoto fails, este hook vai ser triggered. It é designed para trigger quando o módulo carregamento fails em diferente lifecycle stages, e allow users para customize tratamento de erros estratégias.

errorLoadRemote suporta returning um componente de fallback for erro fallback, e também suporta returning specific recurso content para garantir subsequent processes render normally.

We divide o uso de módulo registration e carregamento em "runtime puro + importação dinâmica" e "registro por plugin + importação síncrona".

Pure runtime + importação dinâmica

Ao usar registro em runtime puro, o módulo remoto vai não solicitar recursos until depois registration.

import React from 'react';
import { createInstance, loadRemote } from '@module-federation/enhanced/runtime';
import { RetryPlugin } from '@module-federation/retry-plugin';

// Module registration
const mf = createInstance({
    name: 'host',
    remotes: [
        {
            name: "remote1",
            entry: "http://localhost:2001/mf-manifest.json",
            alias: "remote1"
        }
    ],
    plugins: [
      RetryPlugin({
        retryTimes: 3,
        retryDelay: 1000,
      }),
    ]
});

// Module loading
const Remote1Button = React.lazy(() => loadRemote('remote1/button'));

export default () => {
  return (
    <React.Suspense fallback={<div> Loading Remote1App...</div>}>
      <Remote1Button />
    </React.Suspense>
  );
}

// Method/function loading
loadRemote<{add: (...args: Array<number>)=> number }>("remote1/util").then((md)=>{
    md.add(1,2,3);
});

Use o errorLoadRemote hook para capture carregamento de módulo remoto erros (including recurso carregamento erros), e suporte returning errorBoundary componente de fallback.

import React from 'react';
import { createInstance, loadRemote } from '@module-federation/enhanced/runtime';
import { RetryPlugin } from '@module-federation/retry-plugin';

const fallbackPlugin: () => ModuleFederationRuntimePlugin = function () {
  return {
    name: 'fallback-plugin',
    errorLoadRemote(args) {
      return { default: () => <div> fallback component </div> };
    },
  };
};

// Module registration
const mf = createInstance({
  name: 'host',
  remotes: [
      {
          name: "remote1",
          alias: "remote1"
          entry: "http://localhost:2001/mf-manifest.json",
      }
  ],
  plugins: [
    RetryPlugin({
      retryTimes: 3,
      retryDelay: 1000,
    }),
    fallbackPlugin()
  ]
});

// Module loading
const Remote1Button = React.lazy(() => mf.loadRemote('remote1/button'));

export default () => {
  return (
    <React.Suspense fallback={<div> Loading Remote1App...</div>}>
      <Remote1Button />
    </React.Suspense>
  );
}

// Method/function loading
mf.loadRemote<{add: (...args: Array<number>)=> number }>("remote1/util").then((md)=>{
    md.add(1,2,3);
});

Effect as follows:

Block network request

Block then Habilite

Plugin registration + importação síncrona

Plugin registration suporta usando importação síncrona para carregar módulos, e o momento da solicitação de recursos é earlier than runtime puro, so precisamos registrar o errorLoadRemote hook no plugin.

// rsbuild.config.ts
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'host',
      remotes: {
        remote1: 'remote1@http://localhost:2001/mf-manifest.json',
      },
      runtimePlugins: [
        path.join(__dirname, './src/runtime-plugin/retry.ts'),
        path.join(__dirname, './src/runtime-plugin/fallback.ts'),
      ],
      ...
    }),
  ],
});

Tips

O seguinte exemplo shows como para tratar erros em diferente lifecycle stages.

Se your aplicação scenario é simple, você pode refer para o simplified versão below, que fornece uma unified tratamento de erros solution.

// src/runtime-plugin/fallback.ts
import type { ModuleFederationRuntimePlugin } from '@module-federation/runtime';

interface FallbackConfig {
  // Backup service address
  backupEntryUrl?: string;
  // Custom error message
  errorMessage?: string;
}

const fallbackPlugin = (config: FallbackConfig = {}): ModuleFederationRuntimePlugin => {
  const {
    backupEntryUrl = 'http://localhost:2002/mf-manifest.json',
    errorMessage = 'Module loading failed, please try again later'
  } = config;

  return {
    name: 'fallback-plugin',
    async errorLoadRemote(args) {
      // Handle component loading errors
      if (args.lifecycle === 'onLoad') {
        const React = await import('react');

        // Create a fallback component with error message
        const FallbackComponent = React.memo(() => {
          return React.createElement(
            'div',
            {
              style: {
                padding: '16px',
                border: '1px solid #ffa39e',
                borderRadius: '4px',
                backgroundColor: '#fff1f0',
                color: '#cf1322'
              }
            },
            errorMessage
          );
        });

        FallbackComponent.displayName = 'ErrorFallbackComponent';

        return () => ({
          __esModule: true,
          default: FallbackComponent
        });
      }

      // Handle entry file loading errors
      if (args.lifecycle === 'afterResolve') {
        try {
          // Try to load backup service
          const response = await fetch(backupEntryUrl);
          if (!response.ok) {
            throw new Error(`Failed to fetch backup entry: ${response.statusText}`);
          }
          const backupManifest = await response.json();
          console.info('Successfully loaded backup manifest');
          return backupManifest;
        } catch (error) {
          console.error('Failed to load backup manifest:', error);
          // If backup service also fails, return original error
          return args;
        }
      }

      return args;
    },
  };
};

export default fallbackPlugin;

App.tsx importação síncrona: import Remote1App from 'remote1/app';

About fallback.ts:

errorLoadRemote hook receives um args parameter, que contains o detailed information do erro. Through args.lifecycle nós pode determine o stage do erro occurrence, e take o corresponding processing estratégia:

Handle componente carregamento erros (args.lifecycle === 'onLoad')

Este tipo de erro occurs no módulo processo de carregamento other than o entry recurso mf-manifest.json
We pode retornar um componente de fallback com styles:

if (args.lifecycle === 'onLoad') {
  const React = await import('react');
  const FallbackComponent = React.memo(() => {
    return React.createElement(
      'div',
      {
        style: {
          padding: '16px',
          border: '1px solid #ffa39e',
          borderRadius: '4px',
          backgroundColor: '#fff1f0',
          color: '#cf1322'
        }
      },
      'fallback component'
    );
  });
  FallbackComponent.displayName = 'ErrorFallbackComponent';
  return () => ({
    __esModule: true,
    default: FallbackComponent
  });
}

Handle arquivo de entrada carregamento erros (args.lifecycle === 'afterResolve')

Este tipo de erro occurs no entry recurso mf-manifest.json processo de carregamento
We pode handle it no seguintes two formas:

uma. Try para carregar backup service:

if (args.lifecycle === 'afterResolve') {
  try {
    const response = await fetch('http://localhost:2002/mf-manifest.json');
    if (!response.ok) {
      throw new Error(`Failed to fetch backup entry: ${response.statusText}`);
    }
    const backupManifest = await response.json();
    console.info('Successfully loaded backup manifest');
    return backupManifest;
  } catch (error) {
    console.error('Failed to load backup manifest:', error);
    return args;
  }
}

b. Use local backup recurso:

if (args.lifecycle === 'afterResolve') {
  // Use predefined backup清单
  const backupManifest = {
     id: 'fallback',
     name: 'fallback',
     metaData: {
       name: 'fallback',
       type: 'app',
       buildInfo: {
         buildVersion: 'local',
         buildName: 'fallback',
       },
       remoteEntry: {
         name: 'remoteEntry.js',
         path: '',
         type: 'global',
       },
       types: {
         path: '',
         name: '',
         zip: '@mf-types.zip',
         api: '@mf-types.d.ts',
       },
       globalName: 'fallback',
       pluginVersion: '1',
       publicPath: 'https://example.com/',
     },
     shared: [],
     remotes: [],
     exposes: [],
   };
  return backupManifest;
}

Simplified versão

Se você não precisa distinguish entre erro tipos, você pode também use uma generic tratamento de erros solution:

import type { ModuleFederationRuntimePlugin } from '@module-federation/runtime';

const fallbackPlugin = (errorMessage = 'Module loading failed, please try again later'): ModuleFederationRuntimePlugin => {
  return {
    name: 'fallback-plugin',
    async errorLoadRemote() {
      const React = await import('react');
      const FallbackComponent = React.memo(() => {
        return React.createElement(
          'div',
          {
            style: {
              padding: '16px',
              border: '1px solid #ffa39e',
              borderRadius: '4px',
              backgroundColor: '#fff1f0',
              color: '#cf1322'
            }
          },
          errorMessage
        );
      });
      FallbackComponent.displayName = 'ErrorFallbackComponent';
      return () => ({
        __esModule: true,
        default: FallbackComponent
      });
    },
  };
};
export default fallbackPlugin;

Effect as follows:

Block network request

Block then Habilite

Set ErrorBoundary for componente

React's ErrorBoundary é o último line de defense for handling componente-level erros, no dynamic carregamento scenario de módulos remotos (such as carregamento lazy), ele pode help us capture e process o renderização erros de módulos remotos e forneça graceful degradation.

Setting ErrorBoundary for componentes é suitable for importação dinâmica módulo remoto scenarios, such as carregamento lazy scenarios.

Moreover, depois setting ErrorBoundary for componentes, você pode avoid relying no errorLoadRemote hook for erro fallback, que é uma feature de React itself para forneça erro fallback for your componentes.

App.tsx importação dinâmica módulo remoto

// App.tsx
import React, {
  useRef,
  useEffect,
  ForwardRefExoticComponent,
  Suspense,
} from 'react';

const Remote1AppWithLoadRemote = React.lazy(() => loadRemote('remote1/app'));
const Remote1AppWithErrorBoundary = React.forwardRef<any, any>((props, ref) => (
  <ErrorBoundary fallback={<div>Error loading Remote1App...</div>}>
    <Suspense fallback={<div> Loading Remote1App...</div>}>
      <Remote1AppWithLoadRemote {...props} ref={ref} />
      </Suspense>
    </ErrorBoundary>
));

export default function App() {
  return (
    <>
      <div className="flex flex-row">
        <h2>Remote1</h2>
        <Remote1AppWithErrorBoundary />
      </div>
    </>
  );
}

Effect as follows:

Block network request

Block then Habilite

#Erro handling for renderização do módulo remoto em Module Federation.

#Background

#Solution

#Network layer: Retry mechanism

#Carregamento layer: Erro handling hook

#Rendering layer: Erro boundary

#Add mecanismo de retry

#Registro em runtime puro

#Plugin registration

#errorLoadRemote hook

#Pure runtime + importação dinâmica

#Plugin registration + importação síncrona

#Set ErrorBoundary for componente

Erro handling for renderização do módulo remoto em Module Federation.

Background

Solution

Network layer: Retry mechanism

Carregamento layer: Erro handling hook

Rendering layer: Erro boundary

Add mecanismo de retry

Registro em runtime puro

Plugin registration

errorLoadRemote hook

Pure runtime + importação dinâmica

Plugin registration + importação síncrona

Set ErrorBoundary for componente