Microfrontend Registration Requirements and Technical Integration Constraints in DataHub – DataHub Customer Support Portal

Area: Deployment Issues

Sub-Area: Microfrontend (MFE) Framework Configuration

Issue

Teams integrating a custom UI into DataHub Cloud using Webpack Module Federation need their microfrontend (MFE) registered in the DataHub MFE configuration. This registration cannot be performed through the DataHub UI and must be applied by updating the server-side MFE config file, followed by a restart of the datahub-frontend service. Additionally, there are specific technical constraints around module naming, the mount interface, navigation routing, and API path usage that the MFE must satisfy before it will render correctly inside DataHub.

You Might Be Asking

How do I register a Webpack Module Federation microfrontend in DataHub Cloud?
What technical requirements must my MFE satisfy to integrate with DataHub?
Why is my registered MFE not appearing in the DataHub left navigation?
Can my MFE call the DataHub GraphQL API using the logged-in user's session?
Why does navigating to a sub-path inside my MFE result in a "page not found" error?

Solution

Step 1: Understand the Registration Mechanism

In DataHub Cloud, MFEs are registered by adding an entry to a YAML configuration file that is mounted into datahub-frontend as a ConfigMap. This file is read only at startup, and the browser caches the resulting MFE manifest for approximately 5 minutes. Changes to the MFE config require:

Updating the MFE YAML configuration file for the target environment (staging or production — these are separate files).
Restarting the datahub-frontend service to pick up the new configuration.
Performing a hard refresh in the browser to clear the cached MFE manifest.

Step 2: Prepare Your MFE Configuration Entry

Each MFE entry in the configuration file requires the following fields:

microFrontends:
  - id: <unique-mfe-id>
    label: <Display Label in Navigation>
    path: /<your-mfe-path>
    remoteEntry: https://<your-mfe-host>/mfe/remoteEntry.js
    module: <remoteName>/mount
    flags:
      enabled: true
      showInNav: true
    navIcon: <IconName>

id: A unique identifier for the MFE within DataHub.
label: The text shown in the DataHub left navigation menu.
path: The URL path at which the MFE will be served (e.g., /catalog). Must not conflict with any existing DataHub route.
remoteEntry: The fully qualified HTTPS URL to the MFE's remoteEntry.js file. This URL must be reachable from the browsers of all DataHub users.
module: Must follow the pattern <remoteName>/mount (see Step 3).
navIcon: The name of the icon to display next to the navigation label (e.g., Books, Pulse).

Optionally, if your MFE bundle is large and may exceed the default 10-second load timeout, you can set a custom timeout at the top level of the config file:

loadTimeoutMs: 30000

Step 3: Satisfy the Webpack Module Federation Technical Requirements

Your MFE must be built as a Webpack Module Federation remote and must meet the following requirements:

Remote name matches the module field. The name property in your Webpack ModuleFederationPlugin configuration must exactly match the prefix used in the module field of the MFE config entry.

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

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'myMfeRemoteName',   // Must match the prefix in "module: myMfeRemoteName/mount"
      filename: 'remoteEntry.js',
      exposes: {
        './mount': './src/mount', // Must expose "./mount"
      },
      // ... shared dependencies
    }),
  ],
};

The mount export must be a function, not a React component. The exposed ./mount module must export a function that accepts a DOM element (and optionally an options object), renders into that element, and returns a cleanup function. Exporting a bare React component is not supported.

// src/mount.js (or mount.ts)
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

export default function mount(element, options) {
  ReactDOM.render(<App {...options} />, element);
  return function cleanup() {
    ReactDOM.unmountComponentAtNode(element);
  };
}

React must be bundled with the MFE or correctly declared as a shared singleton, depending on your versioning strategy. Confirm compatibility with the version of React used by DataHub.

Step 4: Understand Navigation and Routing Constraints

DataHub registers only the top-level MFE path as a route (e.g., /mfe/catalog). Sub-paths beneath this route are not registered as DataHub routes. This means:

If a user navigates to a sub-path (e.g., /mfe/catalog/some-product) and performs a full page refresh, they will see a "page not found" error.
All navigation within the MFE must be handled using in-app state, query parameters, or hash-based routing — not by changing the browser's path to a sub-path.

// Example: Use query parameters for in-MFE navigation instead of sub-paths
// Good:  /mfe/catalog?domain=finance&product=trades
// Avoid: /mfe/catalog/finance/trades  (refresh will 404)

Step 5: Calling the DataHub API from Your MFE

Because the MFE runs inside the DataHub page, it shares the authenticated user's browser session. API calls should be made using a relative path so that the DataHub frontend proxy forwards them with the correct session credentials. No service token or separate authentication is needed or recommended.

// Use a relative URL to call the DataHub GraphQL API
const response = await fetch('/api/v2/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: '{ me { corpUser { username } } }' }),
});
const data = await response.json();

Both /api/graphql and /api/v2/graphql are proxied through datahub-frontend and resolve to the same underlying GraphQL endpoint. Standardizing on /api/v2/graphql is recommended as it is the path used by the DataHub UI itself.

Step 6: Verify the MFE is Live

Confirm that the datahub-frontend service has been restarted after the config change.
Perform a hard refresh in your browser (Ctrl+Shift+R / Cmd+Shift+R) or clear the browser cache to bypass the 5-minute MFE manifest cache.
Check that the MFE label appears in the DataHub left navigation menu.
Navigate to the registered path and confirm the MFE renders correctly.
Verify that the remoteEntry.js URL is reachable from your network — if the host is an internal or development environment, ensure all users can reach it.

Additional Notes

Staging vs. Production: Staging and production environments use separate MFE configuration files. Registering an MFE in staging does not affect production. Request a separate configuration change when you are ready to promote to production.
Load Timeout: The default load timeout for remoteEntry.js and module initialization is 10 seconds. For large bundles, set loadTimeoutMs (e.g., 30000 for 30 seconds) at the top level of the MFE config file. This setting applies to all MFEs in that file.
remoteEntry.js Reachability: The remoteEntry.js URL is loaded directly by each user's browser, not by the DataHub server. It must be accessible over HTTPS from the network where your users are located. Development or internal hostnames may not be reachable from all users.
Config UI not available: MFE registration cannot be performed through the DataHub UI in DataHub Cloud. It requires a configuration file change and a service restart managed by the platform team.
Browser caching: After a frontend restart, browsers may still display the old navigation for up to 5 minutes due to caching. A hard refresh will resolve this immediately.
Session security: MFEs should rely on the user's existing DataHub session via relative API calls. Using shared service tokens in a browser-side MFE is not recommended as it bypasses per-user authorization.