Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt

Use this file to discover all available pages before exploring further.

Module Federation lets you split a single-page application into independently built and deployable chunks. At runtime, a host application fetches remote modules over the network and executes them as if they were part of its own bundle. Nx provides generators, executors, and build-system utilities that make Module Federation approachable in a monorepo:

Generators

Scaffold host and remote applications with a single command.

Smart serving

nx serve on the host automatically builds and serves all remotes.

Type safety

Shared ModuleFederationConfig type catches name mismatches early.

Remote caching

Nx Cloud caches unchanged remote builds, so only changed remotes rebuild.

​
Prerequisites

Install the plugin for your framework: 
nx add @nx/react
The @nx/module-federation package is installed automatically as a dependency.

​
Generating a host with remotes

Generate a host application and wire up remotes in a single command: 
nx g @nx/react:host apps/shell --remotes=remote1,remote2
This scaffolds:
  • A host application (apps/shell) with a module-federation.config.ts referencing each remote
  • One remote application per name listed in --remotes
  • Build and serve configuration for every application

​
Generating a remote separately

You can add remotes at any time and attach them to an existing host: 
nx g @nx/react:remote apps/checkout --host=shell
The --host flag causes the generator to update apps/shell/module-federation.config.ts automatically.

​
Module Federation config

Every host and remote has a module-federation.config.ts file that declares the application’s name and, for hosts, the list of remotes: 
// apps/shell/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

const config: ModuleFederationConfig = {
  name: 'shell',
  remotes: ['remote1', 'remote2'],
};

export default config;
The name values must match exactly across host and remote configs — Nx validates this at build time.

​
Excluding or overriding shared libraries

All npm and workspace libraries are shared singletons by default. To exclude a library from sharing (for example, to enable tree shaking): 
const config: ModuleFederationConfig = {
  name: 'shell',
  remotes: ['remote1', 'remote2'],
  shared: (name, sharedConfig) => {
    if (name === 'lodash') {
      return false; // not shared — tree-shaken per application
    }
    return sharedConfig;
  },
};

​
Static vs dynamic federation

Remote URLs are known at build time. The host’s Module Federation config lists remote names and Nx resolves their development ports automatically. For production, explicit URLs are set in a production-specific config:
// apps/shell/webpack.config.prod.js (Angular)
import { withModuleFederation } from '@nx/module-federation/angular';
import moduleFederationConfig from './module-federation.config';

export default withModuleFederation({
  ...moduleFederationConfig,
  remotes: [
    ['remote1', 'https://remote1.example.com'],
    ['remote2', 'https://remote2.example.com'],
  ],
});
Static federation is the simpler approach and suits teams that deploy all applications together on the same release cadence.

​
Developing locally with nx serve

Serve the entire application (host + all remotes) with a single command: 
nx serve shell
Nx detects the remotes that shell depends on and:
  1. Builds each remote (or restores from cache if unchanged)
  2. Serves all remotes statically via a single http-server process
  3. Serves the host via webpack-dev-server or the Rspack dev server with HMR
This keeps local resource usage low even in workspaces with many remotes.

​
Developing a specific remote with HMR

To enable hot module replacement on one or more remotes while working on them:
With Rspack and the @nx/rspack/plugin inference plugin, simply serve the remote directly — the host starts automatically:
nx serve remote1

​
Build configuration with Rspack (React)

For React, Nx uses Rspack by default. The generated rspack.config.ts for a host looks like this: 
// apps/shell/rspack.config.ts
import { NxAppRspackPlugin } from '@nx/rspack/app-plugin.js';
import { NxReactRspackPlugin } from '@nx/rspack/react-plugin.js';
import {
  NxModuleFederationPlugin,
  NxModuleFederationDevServerPlugin,
} from '@nx/module-federation/rspack.js';
import { join } from 'path';
import config from './module-federation.config.js';

export default {
  output: {
    path: join(__dirname, '../../dist/apps/shell'),
    publicPath: 'auto',
  },
  devServer: {
    port: 4200,
  },
  plugins: [
    new NxAppRspackPlugin({
      tsConfig: './tsconfig.app.json',
      main: './src/main.ts',
      index: './src/index.html',
      outputHashing: process.env['NODE_ENV'] === 'production' ? 'all' : 'none',
      optimization: process.env['NODE_ENV'] === 'production',
    }),
    new NxReactRspackPlugin(),
    new NxModuleFederationPlugin({ config }, { dts: false }),
    new NxModuleFederationDevServerPlugin({ config }),
  ],
};

​
Production build

Build the host and all its remotes: 
nx build shell
By default, remotes are not implicit dependencies of the host, enabling independent deployability. If you want to build all remotes together with the host (for a coordinated release), add implicitDependencies to the host’s project.json: 
{
  "name": "shell",
  "implicitDependencies": ["remote1", "remote2"]
}
The production build output is placed in dist/apps/ with one directory per application: 
dist/apps/
├── shell/
├── remote1/
│   └── remoteEntry.js
└── remote2/
    └── remoteEntry.js
Each remoteEntry.js is the entry point the host fetches at runtime.

​
Remote caching with Nx Cloud

Module Federation splits the build into multiple independent processes. Without caching, building each remote separately is slower than a single monolithic build. Nx Cloud makes Module Federation fast by caching each remote’s build output.
When a developer runs nx serve shell, unchanged remotes are restored from cache rather than rebuilt. In a workspace with 100 remotes, only the remotes that changed since the last run are rebuilt.
Connect your workspace to enable remote caching: 
npx nx@latest connect

​
Supported bundler versions

BundlerSupported versions
webpack^5.0.0
@rspack/core^1.6.0
Nx generators install the latest supported versions automatically when scaffolding new projects.

Build docs developers (and LLMs) love

Get started for freeTalk to us