@pawells/react-federation-core

React client library for consuming a Module Federation registry service. Provides a context provider, hooks, and components for discovering, loading, and rendering federated remote modules inside a React application.

Installation

yarn add @pawells/react-federation-core

Setup

Wrap your application with FederationProvider and supply a FederationConfig.

import { FederationProvider, ScriptInjectionLoader } from '@pawells/react-federation-core';

function Root() {
    return (
        <FederationProvider
            config={{
                serviceUrl: 'https://api.example.com/api/v1',
                auth: { bearerTokenFn: () => getAccessToken() },
            }}
        >
            <App />
        </FederationProvider>
    );
}

FederationConfig

FederationAuthConfig — exactly one of:

{ bearerToken: string }                          // static token
{ bearerTokenFn: () => string | Promise<string> } // dynamic token (e.g. from useAuth)
{ apiKey: string }                               // API key header

Loaders

The loader determines how remote entry files are fetched and how modules are extracted from the container.

import { FederationProvider, ViteModuleLoader } from '@pawells/react-federation-core';

<FederationProvider config={{ serviceUrl: '...', loader: new ViteModuleLoader() }}>
    <App />
</FederationProvider>

ScriptInjectionLoader accepts an optional { scriptLoadTimeout?: number } (default 10000 ms).

Components

RemoteComponent

Convenience component that loads and renders a federated module with built-in Suspense and error boundary handling.

import { RemoteComponent } from '@pawells/react-federation-core';

<RemoteComponent
    moduleId="ui-module@1.0.0"
    exposedPath="./Button"
    componentProps={{ label: 'Click me' }}
    fallback={<Spinner />}
    errorFallback={<p>Failed to load module</p>}
/>

RemoteErrorBoundary

Class-based error boundary for remotely-loaded modules. Place it outside the Suspense boundary that wraps lazy remote components. Supports a render-function fallback that receives the error and a reset callback.

import { RemoteErrorBoundary } from '@pawells/react-federation-core';

<RemoteErrorBoundary
    fallback={(error, reset) => (
        <div>
            <p>Error: {error.message}</p>
            <button onClick={reset}>Retry</button>
        </div>
    )}
>
    <Suspense fallback={<Spinner />}>
        <LazyRemoteButton />
    </Suspense>
</RemoteErrorBoundary>

Hooks

useFederatedModule

Loads a federated module and returns a stable React.lazy component reference. Metadata and component references are cached in the FederationContext to prevent duplicate requests and Suspense resets.

import { useFederatedModule } from '@pawells/react-federation-core';

function RemoteButtonWrapper() {
    const LazyButton = useFederatedModule('ui-module@1.0.0', './Button');

    return (
        <Suspense fallback={<Spinner />}>
            <LazyButton label="Click me" />
        </Suspense>
    );
}

useFederationRegistry

Searches and lists modules in the federation registry. Supports filtering, pagination, and manual re-fetching.

import { useFederationRegistry } from '@pawells/react-federation-core';

const { modules, total, isLoading, error, refetch, stats, fetchStats } =
    useFederationRegistry({ query: 'header', limit: 20 });

useFederationContext

Returns the raw FederationContextValue (client, loader, caches) from the nearest FederationProvider. Throws if called outside a provider. Useful when building custom loader or registry integrations.

Error handling

All errors thrown by the library extend FederationError and carry a machine-readable code property.

import { ModuleLoadError, ModuleNotFoundError } from '@pawells/react-federation-core';

try {
    // ...
} catch (error) {
    if (error instanceof ModuleNotFoundError) {
        console.warn('Module not registered:', error.message);
    } else if (error instanceof ModuleLoadError) {
        console.error('Load failed:', error.message, error.cause);
    }
}

Failed module entries are automatically removed from the component cache so the next render retries the load.