Module Federation Runtime APIs; Available in Rspack & Webpack

[ScriptedAlchemy]

Module Federation: The Biggest Update Since Its Inception

Four years after its creation, Module Federation is receiving its most significant update yet. But why redesign Federation?
Let's dive in.

Webpack Users can use the Webpack Plugin
Rspack users, its built into 0.5.0

The Need for Redesign

The introduction of Rspack necessitated a simpler way to maintain support across various bundler tools. To achieve this, we separated Module Federation from Webpack and implemented its runtime as a library. This move liberated federation from a significant portion of bundler lock-in.

Essential Components

The key components of this system include:

• @module-federation/enhanced: This component provides the ModuleFederationPlugin in webpack. In Rspack, it's implemented internally in Rust within the bundler.
• @module-federation/runtime: Both webpack and Rspack depend on this component.
• @module-federation/sdk: This is another component that both webpack and Rspack rely on.
• @module-federation/webpack-bundler-runtime: This component is specific to webpack.
• @module-federation/runtime-tools: A vanity package one can use that exports several of the module federation packages, for easier consumption.

These components might seem overwhelming, so we've made it easier for you. You can use @module-federation/runtime-tools as a comprehensive package. It exports several of the underlying package exports in a user-friendly way, making it easier to work with, less to worry about synchronizing upgrades of various parts.

runtime-tools can also be used in Rspack to override the default @module-federation/* packages that come with rspack. This allows users to upgrade module federation partially without needing to update the rspack core.

The "Federation Runtime"

Contributing to webpack plugins can be daunting due to its steep learning curve which often becomes a discouragement for community contribution. To overcome this challenge, we have shifted the federation runtime to a library. This shift reduces the need for bundler-specific knowledge, making our runtime much more user-friendly and accessible for community expansions and contributions.

The main runtime code that makes module federation what it is has been decoupled from the "bundler runtime" parts. Federation is implemented into bundlers like webpack and rspack by providing bindings for the runtime and initializing it.

Other tool chains could support module federation in a consistent manner if they are able to provide the bundler runtime bindings needed to initialize the runtime.

The "FederationHost" Instances

What is a FederationHost? Each container/runtime is an instance of FederationHost. The "host" application, as we know them, is usually the first FederationHost in the instances. FederationHost is the class that provides additional capabilities (like runtime plugins, hooks, lifecycles, and utilities). We have added a global object that allows you access to all instances: globalThis.__FEDERATION__. If you log this (be it client or server), you should see something like:

This data and more can be accessed via our runtimePlugins APIs as well. In the future, we will expand on the data one has access to.

Runtime Plugins

This is one of the most exciting additions to this initial update. Runtime plugins invert control. At ByteDance, we have many complex requirements and needs for Module Federation. Nearly all of these fell far beyond the scope of what the original plugin was designed to accomplish.

Runtime Plugins were designed to allow us and the community to extend module federation. It introduces the concept of hooks and a lifecycle, something sorely missed in the original plugin design.

Here are the hooks we currently have:

• beforeInit
• Init
• beforeRequest
• afterResolve
• beforeInitContainer
• initContainer
• onLoad
• handlePreloadModule
• errorLoadRemote
• beforeLoadShare
• loadShare
• resolveShare
• beforePreloadRemote
• generatePreloadAssets
• afterPreloadRemote

You can read more in-depth about these hooks here.

Here is an example of a runtimePlugin.

You can find more examples:
https://github.com/module-federation/module-federation-examples/tree/master/runtime-plugins
https://github.com/module-federation/universe/tree/main/apps/runtime-demo

And general Readmes:
https://github.com/module-federation/universe/tree/main/packages/enhanced
https://github.com/module-federation/universe/tree/main/packages/runtime

This specific one is currently what is used in nextjs-mf:

import { FederationRuntimePlugin } from '@module-federation/runtime/types';

export default function (): FederationRuntimePlugin {
  return {
    name: 'next-internal-plugin',
    // if remote is offline
    errorLoadRemote({ id, error, from, origin }) {
      // create a fake page module for next
      const pg = function () {
        console.error(id, 'offline', error);
        return null;
      };
      // add get initial props
      pg.getInitialProps = function (ctx: any) {
        return {};
      };
      let mod;
      // check if this hook is being called at runtime or during build time (like in compiler macros)
      if (from === 'build') {
        mod = () => ({
          __esModule: true,
          default: pg,
          getServerSideProps: () => ({ props: {} }),
        });
      } else {
        mod = {
          default: pg,
          getServerSideProps: () => ({ props: {} }),
        };
      }
      // return a fallback module which will avoid app crash on missing container
      return mod;
    },
    // before any initialization phases start
    beforeInit(args) {
      if (
        // ill check who is calling this hook (workaround for next)
        typeof __webpack_runtime_id__ === 'string' &&
        !__webpack_runtime_id__.startsWith('webpack')
      ) {
        return args;
      }

      // origin allows me to access "this" FederationHost instance
      const { moduleCache, name } = args.origin;
      const gs = (globalThis as any) || new Function('return globalThis')();
      const attachedRemote = gs[name];
      if (attachedRemote) {
        // I add a remote to the module cache manually, in this case next hosts embed their container inside the main runtime
        // So i would not need to load "home" remote if the host is "home",
        // I can attach it to the module cache and federation will not attempt to load remoteEntry.js
        moduleCache.set(name, attachedRemote);
      }

      return args;
    },
    // called as initialization happens
    init(args) {
      return args;
    },
    // before a request is made to a container. 
    // you could modify the request here
    beforeRequest(args) {
      console.log(args.id) //==> home/carousel
      // for example, im redirecting the import to "differentRemote" and importing "differentExposed"
      //args.id = 'differentRemote/differentExposed'
      return args;
    },
    // can return your own HTML script element instead of the default one. 
    // If you wanted to add SRI or other attributes to the script tag, you could do it here
    createScript({ url }) {
      return;
    },
    // The originally requested container exists and exposed modules can be loaded
    afterResolve(args) {
      return args;
    },
    // after import/carousel has loaded, here you could modify or wrap the module.exports before its sent back to consumer
    onLoad(args) {
      return args;
    },
    //Control what shared modules are loaded, and from where. 
    resolveShare(args) {
      // next.js needs react and next/* to be loaded from the host
      // resolveShare allows me to tell everyone they should prefer the hosts versions regardless of what share scope chose. 
      if (
        args.pkgName !== 'react' &&
        args.pkgName !== 'react-dom' &&
        !args.pkgName.startsWith('next/')
      ) {
        return args;
      }
      const { shareScopeMap, scope, pkgName, version, GlobalFederation } = args;

      // Find the host instance dynamically, the host is always the first instance in the array
      const host = GlobalFederation['__INSTANCES__'][0];
      if (!host) {
        // if no host is found, return the original args
        return args;
      }
      // replace the resolver with a function that returns the host version of the module
      args.resolver = function () {
        // update localShareScopeMap (overwrite previous value)
        // as you can see, i am able to access any FederationHost instances original shared modules it can provide, and i can use these directly
        shareScopeMap[scope][pkgName][version] = host.options.shared[pkgName]; // replace local share scope manually with desired module
        // return the resolved share back to consumer
        return shareScopeMap[scope][pkgName][version];
      };
      return args;
    },
    // called before loading shared modules, good place to setup rules ahead of module negotiation
    async beforeLoadShare(args) {
      return args;
    },
  };
}

Community plugins are welcome, and we will provide handy runtimePlugins for common use cases over time. For example, a "retry-runtime-plugin" would be great to provide to the community as an off-the-shelf package.

Future-Proofing our Runtime

Our runtime can be implemented and other tools only need to create the right bindings, making runtime interfaces consistent for everyone. This reduces friction and fragmentation around federation. Bundler teams could support the federation by providing "bundler runtime" packages or bindings.

The Federation plugin uses a significant amount of graph data to create its containers. Using JS hooks to expose this data to a Javascript plugin would create performance problems. It was best implemented in Rust, which meant that we would require a more robust user API to customize how it works, as native code must be compiled into rspacks core.

During the redesign, we focused on:

1. Giving users more control over the "black box" of module federation
2. Offering a sane, user-friendly lifecycle
3. Providing community extension options, allowing "third-party" plugin development
4. Reducing forking the original architecture, ensuring MFP has enough hooks and is designed in a way that doesn't require core class changes for extension.
5. Other Ecosystems, designing the runtime to accommodate future build ecosystems.

Future Plans

• HMR and Fast Refresh: We have had this luxury internally, and intend to release this much-requested DX improvement to public users too.
• Chrome Dev Tools: We will be releasing our chrome dev tools, allowing you to see and interact with the application in a new dimension
• TypeScript Remote Types: Another regularly requested feature is TypeScript support. While there are a few attempts at this already on NPM, the Infra Team at Bytedance has the most integrated and seamless implementation to date. We look forward to releasing built-in support in the near future.
• Improvements to Node Federation: V1.5 should soon provide built-in support for server-side federation, without the need for an additional compiler plugin.
• React Server Components: In close collaboration with members of the remix team, we have proof of concepts in a functional state with React Server Components and Module Federation. We are very encouraged by preliminary outcomes and will watch the progress closely. Proof of Concept

[alikaraarslan]

Hi!
I installed webpack in the current project and I'm developing my react project as 4 modules. Can you develop an example about migrating this project from webpack to rspack?

Thank you for all your work!

[ScriptedAlchemy]

Look at federation examples repo. Many are already migrated

[kindmanspb]

Hello Zack!

Thx a lot for new release and I've a question:

I've multiple dependencies of the same packages with different major versions (by package alias in package.json).
This is needed for backward compatibility of a host application with remote applications with different versions of some package with a context consumer.
Expected and actual results in old Module Federation v1 and new Module Federation v1.5 are different:

Module Federation v1 (old)

Expected result

Both major versions of antd are shared

Input config

const moduleFederationConfig = {
  name: 'app_demo',
  filename: `remoteEntry.js?v=[contenthash]`,
  shared: {
  react: { shareKey: 'react', requiredVersion: '18.2.0', singleton: true },
  'react-dom': {
    shareKey: 'react-dom',
    requiredVersion: '18.2.0',
    singleton: true,
  },
  antd: {
    shareKey: 'antd',
    requiredVersion: '5.13.2',
    singleton: false,
  },
  'antd-4': {
    shareKey: 'antd',
    requiredVersion: '^4.0.0',
    singleton: false,
  },,
};

Webpack share scopes result:

{
  "default": {
    "antd": {
      "4.24.15": {
        "from": "node-starter",
        "eager": false,
        "loaded": 1
      },
      "5.13.2": {
        "from": "node-starter",
        "eager": false,
        "loaded": 1
      }
    },
    "react-dom": {
      "18.2.0": {
        "from": "node-starter",
        "eager": false,
        "loaded": 1
      }
    },
    "react": {
      "18.2.0": {
        "from": "node-starter",
        "eager": false,
        "loaded": 1
      }
    }
  }
}

Actual result

Both versions of antd are shared (expected result is equal)

---

Module Federation v1.5 (new)

Expected result

Both major versions of antd are shared

Actual result

MF picks one of them (the first one)

Input (the same like v1)

Output (FEDERATION.SHARE):

{
  "app_demo": {
    "default": {
      "antd": {
        "4.24.15": {
          "deps": [],
          "useIn": [
            "app_demo"
          ],
          "from": "app_demo",
          "loading": null,
          "version": "4.24.15",
          "scope": [
            "default",
            "default"
          ],
          "shareConfig": {
            "requiredVersion": "^4.24.15",
            "singleton": false,
            "eager": false,
            "strictVersion": false
          },
          "loaded": true,
          "strategy": "version-first"
        }
      },
      "react-dom": {
        "18.2.0": {
          "deps": [],
          "useIn": [
            "app_demo"
          ],
          "from": "app_demo",
          "loading": null,
          "version": "18.2.0",
          "scope": [
            "default"
          ],
          "shareConfig": {
            "requiredVersion": "^18.2.0",
            "singleton": false,
            "eager": false,
            "strictVersion": false
          },
          "loaded": true,
          "strategy": "version-first"
        }
      },
      "react": {
        "18.2.0": {
          "deps": [],
          "useIn": [
            "app_demo"
          ],
          "from": "app_demo",
          "loading": null,
          "version": "18.2.0",
          "scope": [
            "default"
          ],
          "shareConfig": {
            "requiredVersion": "^18.2.0",
            "singleton": false,
            "eager": false,
            "strictVersion": false
          },
          "loaded": true,
          "strategy": "version-first"
        }
      }
    }
  }
}

---

I'm guessing it has to do with the new strategy field, which defaults to 'version-first'.

How to fix it? Example repo:

https://github.com/kindmanspb/mfe-1.5/tree/main

[kindmanspb]

Any news? 👀

[2heal1]

Sorry for replaying latter , we will fix it in next days

[2heal1]

It has been solved , and we will release next Wednesday

[crutch12]

It has been solved , and we will release next Wednesday

Released?

[2heal1]

yes, you can upgrade [email protected] to test

[Onlylonger]

Sorry for asking a old webpack internal MF plugin question.

how to catch the ScriptExternalLoadError: Loading script failed error when my remote app not serve for host app. thx

@ScriptedAlchemy

[vdorchan]

There seems to be no support for vite, the plugin is packaged with esm, federation runtime is not supported
似乎没法支持 vite，使用该插件打包出来的是 esm，federation runtime 无法支持
https://github.com/originjs/vite-plugin-federation