@epam/microfrontends

This package contains utilities and scripts which simplify development of micro-frontends.

Definitions

• Remote app - the application which hosts remote widgets.
• Host app - the application which renders remote widgets.
• Remote facade (widgets.js) - the unified interface which is hosted on "Remote app" and is used by "Host app" to render remote widgets.

Main idea

"Host App" retrieves remote widgets from "Remote app" using "Remote facade" which is located at well known URL.

It's better described by example. Let's assume that the "Remote app" is hosted on this origin: "http://127.0.0.1:4000" Host knows that "Remote facade" is located at well known URL which looks like this: "http://127.0.0.1:4000/widgets.js" There several other resources which are hosted by the "Remote app", and the "Host" doesn't know about presence of such resources. Though, they are used implicitly (by widgets.js) during the mount of the remote widgets. Here the list of resources:

• Remote Assets Manifest (http://127.0.0.1:4000/<path_to_build_manifest>)
• Remote App JS bundle (http://127.0.0.1:4000/<path_to_main_js_bundle>)
• Remote App CSS bundle (http://127.0.0.1:4000/<path_to_main_css_bundle>)

Below is the sequence of actions which are performed by the Host in order to mount remote widget.

1. LOAD

   // The "Remote facade" is loaded using well-known URL. Internally, the Host loads the widget like this.
   const remote = await import('http://127.0.0.1:4000/widgets.js');

2. INIT

   /**
   * Several IMPLICIT actions are done during the init(). Host doesn't know anything about the actions, they are incapsulated inside the "widgets.js".
   * 1) "Remote Assets Manifest" file is loaded
   * 2) URL to the "Remote App JS bundle" is determined from the manifest
   * 3) URL to the "Remote App CSS bundle" is determined from the manifest
   * 4) window.Widgets global variable is created (unless already defined). It acts as a simple registry which helps to define/require widgets
   * 5) "Remote App JS bundle" is loaded via window.Widgets.require(/../) Note: "script" tag is used under the hood to load the JS bundle. It's loaded only ones and cached.
   * 6) widgets which are defined during the load (via the window.Widgets.define(...)) are collected.
   * Note: The "Remote App CSS bundle" is NOT loaded on this step. It will be loaded later, during widget "mount".
   */
   const widgets = await remote.init();

3. MOUNT

   // The "Remote App CSS bundle" is loaded as part of this call (right before actual mount occurs)
   const { unmount } = widgets['demoWidget'].mount(/*...*/);

4. UNMOUNT

   // The "Remote App CSS bundle" is unloaded after this step.
   unmount();

Usage example

(Remote) Generate remote facade (widgets.js)

Run the command below from the "remote" project's root folder. It creates "Remote facade" files and puts them to the ./public folder. NOTE: it needs to be run at the very first time and can only be run again when the @epam/microfrontends package version has changed.

# Example for CRA
# Option 1 (when "@epam/microfrontends" is installed locally)
npx epam-microfrontends-init --app-type=webpack
# Option 2
npx --yes @epam/microfrontends@latest epam-microfrontends-init --app-type=webpack

Next files will be created:

• widgets.js (+ widgets.js.map) - The minified version of the "Remote facade" which is hosted on the remote side. The Host app downloads and runs this file in order to retrieve remote widgets.
• widgets.dev.js and widgets-dev.html - The non-minified version of the "Remote facade". It might be used as a starting point to test remote widgets locally in isolation. NOTE: It's safe to remove these files unless you plan to locally test your widgets via "widgets-dev.html".

All options:

(Remote) Implement remote widgets

import { createRoot } from 'react-dom/client';
import { IHistoryMicroFe } from '@epam/microfrontends/helpers/history';
const demoWidget = {
    mount: (target: HTMLElement, params: any) => {
        /*
         * If a remote widget uses routing, then it's necessary to do all routing via the "params.historyMicroFe".
         * Use "params.historyMicroFe" directly or via converters exported from "@epam/microfrontends/helpers/history"
         */
        const root = createRoot(target);
        root.render(<DemoWidgetComponent />);
        return {
            unmount: () => {
                root.unmount();
            }
        }
    }
};
if (isPartOfTheNormalApp) {
    // render app
}
(window as any).Widgets?.define(() => ({
    demoWidget,
}));

(Host) Consume the remote widgets

import { RemoteWidget, RemoteWidgetContext } from '@epam/microfrontends/helpers/react';
import { IHistory4Full_to_IHistoryMicroFe } from '@epam/microfrontends/helpers/history';
import { createBrowserHistory } from 'history';
//...//
const history = createBrowserHistory();
const historyMicroFe = IHistory4Full_to_IHistoryMicroFe(history as any);
//...//
function App() {
    // Somewhere in the app:
    const params = { historyMicroFe };
    return (
        <RemoteWidgetContext.Provider value={params}>
            <RemoteWidget
                url="http://172.20.0.1:4001/widgets.js"
                name="demoWidget"
            />
            <RemoteWidget
                url="http://172.20.0.1:4002/widgets.js"
                name="demoWidget"
            />
        </>
    )
}

Routing in remote widgets

If some remote widget uses routing, then it's expected that it should use "historyMicroFe" standard interface which is provided by the "Host app". In general case, host and remote could use different routers, e.g.: (HOST: unknown 1) ---> (IHistoryMicroFe) --> (REMOTE: unknown 2)

In such situation, some adapters will be required:

1. unknown 1 -> IHistoryMicroFe
2. IHistoryMicroFe -> unknown 2

There are several adapters available OOTB in this package. They cover some typical uses cases:

• IHistory4Full_to_IHistoryMicroFe
• IRouter6_to_IHistoryMicroFe
• IHistoryMicroFe_to_IHistoryRouter6
• IHistoryMicroFe_to_IHistory4Full

Usage of "basename"

• It's expected that "Host app" doesn't use "basename" feature of router. So that full location path is exposed to "Remote app".
• The "Remote app" may optionally use "basename" for its routing if needed. See the example here: packages/examples/remotes/cra-router5/src/widgets/demoWidget/demoWidget.tsx

Features of the "Remote facade" (widgets.js)

• Possibility to customize mount, possible options:
  • shadowRoot
  • global
  • skip
• Provides "Widgets" module system which supports loading bundles of next formats: iife, esm
• Processed with Babel to guarantee compatibility with browsers
• Error handling
• Corner cases handling
• Encapsulates logic of parsing different types of assets manifest files
• It's hosted only on remote side, because it contains logic specific to the remote app.