Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Module Federation app crashes on start with 'Shared module is not available for eager consumption'

ErrorUncaught Error: Shared module is not available for eager consumption

Short answer

Module Federation fills the shared scope (react, react-dom) asynchronously. If your entry file imports React straight away, the code runs before that scope is ready and throws. Move the startup code into a bootstrap file and load it with a dynamic import(). Use eager: true on the shared module only when you cannot change the entry.

  • Applies to webpack 5, Module Federation plugin, React 19, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the file that is the webpack entry (usually src/index.js) and check whether it imports React, ReactDOM or your App at the top level. If it does, the first cause below applies.

    grep -n "entry" webpack.config.js
    head -20 src/index.js
  2. 2Match what you see, then jump to its fix

    1. 1The error appears in the browser console on page load, and the stack points at the entry chunk (main.js or index.js).The entry file runs synchronously, with no async boundaryFix
    2. 2The entry file is generated or owned by something else (a shell or a template), and the error names one specific shared package such as react.You cannot add a boundary to this entry, so the shared module must be provided eagerlyFix

What does the error look like?

  • Uncaught Error: Shared module is not available for eager consumption
  • Shared module is not available for eager consumption: webpack/sharing/consume/default/react/react

Cause 1 of 2

The entry file runs synchronously, with no async boundary

1Check

Look at the entry file. If it has static imports such as react-dom/client and ./App and calls createRoot straight away, the shared modules are requested before the share scope has been initialised.

cat src/index.js

2Fix

Make the entry a one-line dynamic import and move the old startup code into a new file called bootstrap.js. The dynamic import creates the async boundary that gives Module Federation time to set up the shared scope.

// src/index.js
import('./bootstrap');

// src/bootstrap.js
import { createRoot } from 'react-dom/client';
import App from './App';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

3Verify

Rebuild and reload the page. The console error is gone and the app renders.

npx webpack serve

Confirmed by webpack.js.org

Did this fix it?

Cause 2 of 2

You cannot add a boundary to this entry, so the shared module must be provided eagerly

1Check

Look at the shared option of ModuleFederationPlugin. A shared module that is not eager is delivered through an asynchronous request, which an eagerly executed entry cannot wait for.

grep -n -A8 "shared" webpack.config.js

2Fix

Mark the dependency as eager in the advanced shared syntax. The webpack docs say to do this in one place only, for example the shell, because eager modules and their fallbacks are always downloaded. The async bootstrap from the first cause is the recommended fix.

new ModuleFederationPlugin({
  shared: {
    ...deps,
    react: {
      eager: true,
    },
  },
});

3Verify

Rebuild the shell and reload. The error no longer appears for that package.

npx webpack

Confirmed by webpack.js.org

Did this fix it?

How do I stop it coming back?

  • Start every Module Federation app and remote from a tiny index file that only does import('./bootstrap').
  • Share react and react-dom with singleton: true so only one copy runs on the page.
  • Use eager: true in a single place only, because its modules are always downloaded.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.