The OpenMicrofrontends project aims to provide a formal specification for Microfrontends provided by a server. Think of it as OpenAPI for Microfrontends.

The project just released version 1.0.0 of the specification and a generator to create type-safe integration code on the Microfrontend- and Host Application-side.

Example Description:

$schema: https://open-microfrontends.org/schemas/1-0-0.json
openMicrofrontends: 1.0.0
servers:
- url: 'http://localhost:7890'
  description: Local Test Server
microfrontends:
- name: My First Microfrontend
  assets:
    basePath: /public
    js:
      moduleSystem: ESM
      initial:
        - Microfrontend.js
  rendererFunctionName: startMyFirstMicrofrontend
  config:
    schema:
      type: object
      properties:
        welcomeMessage:
          type: string
      required: ["welcomeMessage"]
    default:
      welcomeMessage: Hello World!
  messages:
    ping:
      publish: true
      subscribe: true
      schema:
        type: object
        properties:
          ping:
            const: true
        required: ["ping"]

Find out more on the project homepage.

The upcoming Mashroom Server v3 will include first class support for OpenMicrofrontends compliant Microfrontends!

OpenMicrofrontends Specification Released was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

This is mainly a maintenance release with a lot of 3rd party libraries upgraded and some code improved.

Notable changes

• Support for Node.js 24 added
• With Node.js 24 all Mashroom config files can now be written in TypeScript (because the types are automatically stripped, check https://nodejs.org/docs/latest-v24.x/api/typescript.html#typescript-features for limitations)
  An example mashroom.ts main config file could look like this:

import type {MashroomServerConfig} from '@mashroom/mashroom-json-schemas/type-definitions';

const serverConfig: MashroomServerConfig = {
    name: 'My Server',
    port: 5050,

    // ...
};

export default serverConfig;

• Dropped support for Node.js 18
• Made sure the redirectUrl parameter of the Portal login and logout route cannot be abused to redirect to arbitrary hosts (and to obscure the actual referrer)

As usual, you can check the CHANGELOG for a list of all changes.

To try out the new Mashroom Server version: Clone the Mashroom Portal Quickstart repository and follow instructions in the README!

Mashroom Server 2.9 released was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

New Features

Theme Overhaul

We have improved the style of the default Theme and introduced a Dark Mode. The theme also exposes now a lot of CSS variables that can be used in Apps to align the style.

Additionally, we added the possibility to pass a override CSS file that can be used to customize the theme:

"Mashroom Portal Default Theme": {
    "darkMode": "auto",
    "styleFile": "./defaultThemeOverrides.css"
},

:root {
  --mashroom-portal-color-primary: green;
}

Improved Sandbox App

The Sandbox App shows now a permanent link for the current session that can easily be shared with other people.

Furthermore it shows now unavailable (non permitted) Apps in the selection, just to make clear what the problem is in case a user expects a specific App.

New App Gallery App

We have introduced a new App Gallery that shows all registered Apps with some details and screenshots.

Simplified Server-Side Rendering

The client-side bootstrap of an App receives now a flag that indicates if the App has been rendered on the server-side. This can be used to decide if you need to hydrate or just client-side render.

if (portalAppSetup.serverSideRendered) {
   root = hydrateRoot(portalAppHostElement, (
       <App />
   ));
} else {
   // Default: render on client side
   root = createRoot(portalAppHostElement);
   root.render((
       <App />
   ));
}

The server-side bootstrap can now return some script that needs to be injected into the header. This is useful if you want to pass some state to the client-side. Or if the UI framework also creates some script during server-side rendering (like Svelte).

const ssrBootstrap: MashroomPortalAppPluginSSRBootstrapFunction = async (portalAppSetup) => {
    const {appId} = portalAppSetup;
    
    // TODO: Load data and render
    let someLoadedData = {};
    let html = '';
    
    return {
      html,
      injectHeadScript: `
        window['__my_data_${appId}'] = ${JSON.stringify(someLoadedData)};
      `
     };
};

Bugfixes

• Fixed handling of multiple Modal Apps at the same time: Only the latest is shown at a time and on close the next one (the one “below”) will get visible.
• Fixed the errors that were occurring in some plugins when mashroom-monitoring-metrics-collector was not present

Checkout the CHANGELOG for a list of all changes.

To try out the new Mashroom Server version: Clone the Mashroom Portal Quickstart repository and follow instructions in the README!

Mashroom Server 2.8 released was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

Notable features

New authentication expiration strategies

It is now possible to configure what should happen if the authentication expires in the Portal. Until now the strategy was to just reload the current page, now you can choose between multiple strategies:

• stayOnPage
• reload (Default, same behaviour as before)
• redirect (redirect to another page)
• displayDomElement (set display: block on the DOM element with given ID)

Can be configured like this:

"Mashroom Portal WebApp": {
  "authenticationExpiration": {
    "warnBeforeExpirationSec": 30,
    "onExpiration": {
      "strategy": "stayOnPage"
    }
  }
}

Please note, the warnBeforeAuthenticationExpiresSec and autoExtendAuthentication properties have been removed from the config schema but are still recognised and will be merged into the new config object.

A configuration like the one above would let the Portal stay on the page after session expiration and just show a message:

Portal Proxy can add x-forwarded-* headers

If enabled, the Portal Proxy automatically adds the following headers (and merges them with incoming headers):

• x-forwarded-for
• x-forwarded-host
• x-forwarded-proto

Can be enabled like this:

"Mashroom Http Proxy Services": {
    "createForwardedForHeaders": true
}

Bugfixes

• VHost Mapper Plugin: Replaces the absolute location header URLs with the relative path if the host matches the frontend host. This saves an unnecessary round trip if the protocol does not match the frontend protocol.
• Session Plugin: Use session cookies by default, otherwise the session could expire on the “client-side” which is kinda weird.

Checkout the CHANGELOG for a list of all changes.

To try out the new Mashroom Server version: Clone the Mashroom Portal Quickstart repository and follow instructions in the README!

Mashroom Server 2.7 released was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

Version 2.6 of the Microfrontend Integration Platform Mashroom Server has been released today.

This is manly maintenance release with no breaking changes. We have updated all 3rd party libraries and introduced some measures to improve supply chain safety.

Notable changes and fixes

• HTTP Proxy: We have added support for transforming the request/response body. Proxy interceptors can now return streamTransformers (implementing stream.Transform) and can be used to compress/encrypt the communication to backend servers.
  Compression example:

import zlib from 'node:zlib';

export default class MyInterceptor implements MashroomHttpProxyInterceptor {
   async interceptRequest(targetUri) {
       if (targetUri.startsWith('https://my-backend-server.com')) {
           return {
               addHeaders: {
                   'content-encoding': 'gzip',
               },
               streamTransformers: [
                   zlib.createGzip(),
               ],
           };
       }
   }
   async interceptResponse(targetUri, existingHeaders) {
       if (targetUri.startsWith('https://my-backend-server.com') 
&& existingHeaders['content-encoding'] === 'gzip') {
           return {
               removeHeaders: [
                   'content-encoding',
               ],
               streamTransformers: [
                   zlib.createGunzip(),
               ],
           };
       }
   }
}

• Fixed the problem that remote subscriptions can receive the same message multiple times if subscription patterns overlap.
  See issue #115
• Mashroom modules are now built in a safe environment with lifecycle scripts of 3rd party libraries disabled. Additionally provenance attestations are generated and can be checked via npm audit signatures and on npmjs.com:

To try out the new Mashroom Server version: Clone the Mashroom Portal Quickstart repository and follow instructions in the README!

Mashroom Server 2.6 released was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

Version 2.5 of the Microfrontend Integration Platform Mashroom Server has been released today.

With this release we focused on housekeeping, like cleaning up the code base and upgrading or removing/replacing deprecated and unmaintained libraries.

Notable changes and fixes

• We discovered and fixed a potential memory leak that occurred when Remote App servers didn’t answer requests (or the network just dropped the connection). Now all requests have a proper timeout set and sockets will be closed and removed.
• The File Store doesn’t check for external changes with every access anymore, but waits the configured checkExternalChangePeriodMs (default 100ms). This reduces I/O and should slightly improve the performance.
• The default HTTP proxy (for API calls) has been rewritten because node-http-proxy is no longer maintained. The new implementation uses the Stream API introduced with Node.j 10, which has an improved error handling and resource cleanup.
• Mashroom uses now the OpenTelemetry SDK for metrics. To add custom metrics you can still use the MashroomMonitoringMetricsCollectorService or directly the OpenTelemetry API, like so:

const collectorService: MashroomMonitoringMetricsCollectorService = req.pluginContext.services.metrics.service;

const meterProvider = collectorService.getOpenTelemetryMeterProvider();
const meter = meterProvider.getMeter('my_meter');
const counter = meter.createCounter('http_request_counter', {
    description: 'HTTP Request Counter',
});

counter.add(1);

Breaking Changes

• The most breaking changes are related to metrics:
  - The metrics collector service API (MashroomMonitoringMetricsCollectorService) has been changed
  - Some metrics have been renamed
  - The way how you can fetch metrics from a specific PM2 worker via inter-process communication has changed
• The type of request.session is no longer any, so if you want to add custom properties to the session you have to extend the type like this:

declare module 'express-session' {
  interface SessionData {
    foo?: string;
  }
}

• Support for Node.js 16 has been dropped
• For more details, checkout the CHANGELOG

To try out the new Mashroom Server version: Clone the Mashroom Portal Quickstart repository and follow instructions in the README!

Mashroom Server 2.5 released was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

We have overhauled our Microfrontend Platform Demo and fixed a few problems.

• We tried to simplify and slim down the k3d based demo; the script sets now up the whole platform in (under 5min on a M1 Pro)
• Works now on Apple Silicon chips (ARM64)
• Common services and Microfrontends are now in different namespaces and the Portal is set up to search Microfrontends in namespaces with specific labels
• The Microfrontend deploy scripts create now a new version with every build which automatically busts the browser cache
• New Microfrontend versions are now registered faster (< 60sec)
• All components updated to the latest version

Check it out: https://github.com/nonblocking/microfrontend-platform-kubernetes!

Kubernetes Microfrontend Platform Demo updated was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

Version 2.4 of the Microfrontend Integration Platform Mashroom Server has been released today.

Improved HTTP/WebSocket Proxy

The mashroom-http-proxy plugin (amongst others used to forward Microfrontend requests to the backend) allows now a more fine grained pool configuration.

For HTTP/S request you can now not only limit the number of sockets per target host, but also the total sockets and the number of waiting requests per host. The latter can limit the damage by unresponsive backends, because it prevents reverse proxy connection pools from filling up.

For WebSocket connections you can now limit the connections per host and the total connections.

Example configuration:

{
    "plugins": {
        "Mashroom Http Proxy Services": {
            "poolMaxTotalSockets": 100,
            "poolMaxSocketsPerHost": 10,
            "poolMaxWaitingRequestsPerHost": 100,
            "socketTimeoutMs": 60000,
            "wsMaxConnectionsTotal": 2000,
            "wsMaxConnectionsPerHost": 500
        }
    }
}

Additionally, the HTTP Proxy Plugin exposes new metrics like the number of sockets and waiting requests per host (see screenshot at the top).

Messaging via Redis Pub/Sub

Redis can now be used as external messaging broker (besides AMQP and MQTT). An external messaging broker is necessary if you want to send messages to/from 3rd party systems in your Microfrontend, or to other browser instances of the same or other users.

Other notable changes and fixes

• Support for Node.js 20, support for 14 has been dropped
• There are a number of small breaking changes, checkout the CHANGELOG

To try out the new Mashroom Server version: Clone the Mashroom Portal Quickstart repository and follow instructions in the README!

Mashroom Server 2.4 released was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

Mashroom Portal treats Microfrontends as blackbox and doesn’t care which UI Framework and which bundler is used. But if you have a lot of Microservices with the same Vendor libraries built with webpack it makes sense to enable Module Federation, because it can lead to significant reduced bundle sizes and faster loading.

Note: I already covered generic (bundler independent) ways to reduce the bundle sizes in this article.

Differences to the typical Microfrontend approach with Module Federation

If you use Module Federation in conjunction with Mashroom Portal there are a few main differences compared to a typical setup:

1. There is no Host App. In Mashroom Server there is no Host/Shell App that takes over the whole browser and is responsible for loading remote components or Apps. As mentioned before, Mashroom treats all Microservices as blackboxes which shouldn’t expose any global variables except a bootstrap. So, Modules Federation cannot share anything out-of-the-box because global webpack variables such as __webpack_share_scopes__ are missing.
2. Only Mashroom Portal knows where the remotes are. Only Mashroom Portal knows which Apps exist and how to load them. So, that cannot be done by Module Federation.
3. The remote containers need to be initialised manually. Because auf 2., Module Federation cannot not automatically initialise the containers and enable sharing, so, the Dynamic Remote Containers approach needs to be used.

Working Solution

Starting Situation

Lets say we have a bunch of simple React Apps with the following setup:

Bootstrap:

// index.tsx
const bootstrap: MashroomPortalAppPluginBootstrapFunction = 
  (portalAppHostElement, portalAppSetup, clientServices) => {
    const {appConfig, user} = portalAppSetup;
    const {messageBus} = clientServices;

    const root = createRoot(portalAppHostElement);
    root.render(<App appConfig={appConfig} messageBus={messageBus}/>);

    return {
        willBeRemoved: () => {
            root.unmount();
        }
    };
};

window.startMyReactApp = bootstrap;

Mashroom Plugin Config:

"mashroom": {
    "devModeBuildScript": "build",
    "plugins": [
        {
            "name": "My React App",
            "type": "portal-app2",
            "clientBootstrap": "startMyReactApp",
            "resources": {
                "js": [
                    "index.js"
                ]
            },
            "local": {
                "resourcesRoot": "./dist"
            }
        }
    ]
}

Webpack Config:

// webpack.config.js
module.exports = {
    entry: __dirname + '/src/index.tsx',
    output: {
        path: __dirname + '/dist',
        filename: 'index.js',
    },
};

Switch to async loading

To make sharing work we first of all have to load the actual App asynchronously via import(). So, copy index.tsx to bootstrap.tsx and export it as default:

// bootstrap.tsx
const bootstrap: MashroomPortalAppPluginBootstrapFunction = 
  (portalAppHostElement, portalAppSetup, clientServices) => {
    const {appConfig, user} = portalAppSetup;
    const {messageBus} = clientServices;

    const root = createRoot(portalAppHostElement);
    root.render(<App appConfig={appConfig} messageBus={messageBus}/>);

    return {
        willBeRemoved: () => {
            root.unmount();
        }
    };
};

export default bootstrap;

And (for the moment) create a new index.tsx with that just imports the bootstrap:

// index.tsx
const bootstrap: MashroomPortalAppPluginBootstrapFunction = 
  (portalAppHostElement, portalAppSetup, clientServices) => {
    const bootstrap = await import('./bootstrap');
    return bootstrap.default(portalAppHostElement, portalAppSetup, clientServices);
};

window.startMyReactApp = bootstrap;

Also, make sure you have a proper code splitting configuration, which means the chunks names contain the content hash to prevent caching problems:

output: {
    path: __dirname + '/dist',
    filename: 'index.js',
    chunkFilename: 'chunk.[contenthash].js', // Change
},

Create a Module Federation container for sharing

Next step is to configure the ModuleFederationPlugin: We create a container with a unique name and export is as app.js. But most importantly, we shared the vendor libraries:

// webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
const { dependencies } = require('./package.json');

module.exports = {
  // ...
  plugins: [
      new ModuleFederationPlugin({
          name: '__my_react_app__',
          filename: 'app.js',
          exposes: {
              bootstrap: __dirname + '/src/bootstrap.tsx',
          },
          shared: {
              react: {
                  singleton: true,
                  requiredVersion: dependencies.react,
              },
              'react-dom': {
                  singleton: true,
                  requiredVersion: dependencies['react-dom'],
              },
              // Other libraries
          },
      })
  ]
}

Please note, we use the singleton flag here for react and react-dom because those libraries use a global state and shared UI components wouldn’t work otherwise. This is typically not recommended, because singleton means to share a library even if the version does not match.

We also have to add the created app.js to the resources to load by Mashroom Portal:

"resources": {
    "js": [
        "app.js",
        "index.js"
    ]
},

Load the App with enabled sharing

The last step is to fix the App bootstrapping so the Vendor libraries are actually shared among different Apps on a Portal page.

What we do is we follow the guideline for Dynamic Remote Containers but additionally manually expose the __webpack_share_scopes__ variable to the window object. So, the resulting index.tsx would look like this:

// index.tsx
const bootstrap: MashroomPortalAppPluginBootstrapFunction = async (
    portalAppHostElement,
    portalAppSetup,
    clientServices,
) => {
    const sharedScopes = window.MASHROOM_WEBPACK_SHARED_SCOPE || __webpack_share_scopes__;
    window.MASHROOM_WEBPACK_SHARED_SCOPE = sharedScopes;
    await __webpack_init_sharing__('default');
    await __my_react_app__.init(sharedScopes.default);
    const bootstrapModule = await __my_react_app__.get('bootstrap');
    const bootstrap = bootstrapModule();
    return bootstrap.default(portalAppHostElement, portalAppSetup, clientServices);
};

window.startMyReactApp = bootstrap;

For TypeScript you also have to add these declarations:

declare const __my_react_app__: any; // Module Federation container
declare const __webpack_share_scopes__: any;
declare const __webpack_init_sharing__: any;
declare global {
    interface Window {
        MASHROOM_WEBPACK_SHARED_SCOPE: any;
        startMyReactApp: MashroomPortalAppPluginBootstrapFunction;
    }
}

Optional: Unload all chunks properly

It you need to unload Apps dynamically or want to use hot reload it is necessary to manually remove all chunks by deleting the global variable webpackChunk_<npm_module_name> (e.g. for my-react-app this would be webpackChunk_my_react_app):

// bootstrap.tsx
const bootstrap: MashroomPortalAppPluginBootstrapFunction = 
  (portalAppHostElement, portalAppSetup, clientServices) => {
    // ...
    return {
        willBeRemoved: () => {
            delete window.webpackChunk_my_react_app;  // Add this
            root.unmount();
        }
    };
};

export default bootstrap;

And thats it, if you apply this change to all of your Microfrontends they will automatically share the Vendor libraries (if the versions match or singleton is set).

I’ve adapted mashroom-portal-demo-react-app and mashroom-portal-demo-react-app2 in the Mashroom git repo and it really makes a difference:

Before:

After:

So, the App loaded secondly (the right one) is about 120k smaller, which is approximately the size of the React runtime.

Possible disadvantages

• All Teams contributing Microfrontends need to use webpack as a bundler
• The approach leads to a lot more chunks and additional HTTP requests that could impact the performance of the initial loading if you have a lot of Microfrontends on a page (because of the Browser connection limitation)

Using Webpack Module Federation in Mashroom Portal was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.

In this article I demonstrate how to extend Mashroom Server functionality by ability to define GraphQL interfaces with this 3rd party plugin.

GraphQL is an open-source query and manipulation language for APIs. In contrast with REST it allows client to define structure of data required from server.

Key concept of the Mashroom server is its pluggable system. Except its tiny core — everything is just a plugin. You write a new API for your app, or just a middleware checking or enriching incoming request — you do it by creating a new plugin.

This concept is also reused in GraphQL Plugin for Mashroom Server. You create a new plugin defining your schema and Mashroom Server exposes it as an API.

Before you create first GraphQL Schema, you need to install Mashroom GraphQL plugin to allow Mashroom Server to recognize and to load GraphQL Schemas.

npm i -S mashroom-graphql-server

After successful installation, you can start to create your first GraphQL Schema.

Whole example can be found in this repository

Each plugin has to have proper definition. Place it in separate mashroom.json file or just into package.json

{
  "name": "Mashroom GraphQL Person Plugin",
  "type": "mashroom-graphql-plugin",
  "bootstrap": "./dist/bootstrap.js",
  "defaultConfig": {
    "pubSub": "memory"
  }
}

When Mashroom Server detects a plugin it tries to load and bootstrap it. Therefore — a bootstrap method needs to be created too

const bootstrap: MashroomGraphQLPluginBootstrapFunction = (pluginName, config, contextHolder, pubSub) => {
  return Promise.resolve(new PersonGraphQLPlugin(pubSub));
}

Now it’s time to create GraphQL schema

getSchema(): DocumentNode | Array<DocumentNode> | string | Array<string> {
  return gql`
    type Person {
      id: ID!
    }

    type Query {
      personByName(id: ID!): Person
      createPerson(id: ID!): Person
    }
    
    type Subscription {
      personCreated: Person
    }
  `;
}

getResolvers(): IResolvers | Array<IResolvers> {
    return {
      Query: {
        personByName: (parent, args) => {
          return {
            id: args.id,
          };
        },

        createPerson: (parent, args) => {
          setTimeout(() => {
            this.getPubSub().publish('PERSON_CREATED', {
              personCreated: {
                id: args.id,
              },
            });
          }, 1500);
        },
      },
      Subscription: {
        personCreated: {
          subscribe: () => this.getPubSub().asyncIterator(['PERSON_CREATED']),
        },
      },
    }
  }

To run Mashroom Server with GraphQL and Websocket support you need to create a customer starter:

const { server, expressApp, loggerFactory } = await mashroomServerContextFactory(resolve('src', 'testserver'));

await server.start();

await startGraphQLServer(server._httpServer, expressApp, loggerFactory);

Once started, open http://localhost:5050/graphql in your web browser.

You can define as many GraphQL Schemas as you need. Mashroom GraphQL Plugin stitches them together fully automatically.

Links and references

Mashroom GraphQL Plugin

Example used in the article

Mashroom Documentation

GraphQL

GraphQL Plugin for Mashroom Server was originally published in Mashroom Server on Medium, where people are continuing the conversation by highlighting and responding to this story.