create-mfe

Create a Micro-Frontend (MFE)

This workspace uses @module-federation/vite with @analogjs/platform (Analog.js) on top of Nx. The host is apps/web-app (port 4200). Additional remotes follow the pattern of apps/counter-remote (port 4201+).

Architecture overview

apps/
  web-app/          ← host (Analog SPA, port 4200)
  counter-remote/   ← remote (Analog SPA, port 4201)
libs/
  counter/          ← workspace lib exposed by counter-remote

The remote exposes one route file (./Routes). The host lazy-loads it via loadChildren. The two apps share Angular, CDK, Material, NgRx, and RxJS as MF singletons so only one copy of each runs in the browser.

Step 0 – Generate the remote app

pnpm nx generate @analogjs/platform:app my-remote --directory=apps/my-remote

Replace the generated vite.config.ts with the template in Step 3. Keep the generated app shell files (src/main.ts, src/app/app.ts, src/app/app.config.ts, src/app/app.routes.ts) — the remote needs these to run as a standalone app via nx serve and in Playwright. Wire app.routes.ts to spread the feature routes and add a wildcard fallback:

// apps/my-remote/src/app/app.routes.ts
import { Route } from '@angular/router';
import { myFeatureRoutes } from '@myorg/my-feature';

export const routes: Route[] = [...myFeatureRoutes, { path: '**', redirectTo: '' }];

Delete generated pages/routes you don't need — the remote exposes its feature via remote-routes.ts, not via Analog file-based routing.

Step 1 – Create the workspace lib

Generate the feature lib if it doesn't exist:

pnpm nx generate @nx/angular:library my-feature --directory=libs/my-feature --standalone

Create libs/my-feature/src/lib/lib.routes.ts. Use loadComponent so the component is still lazy-loaded by Angular's router:

// libs/my-feature/src/lib/lib.routes.ts
import { Route } from '@angular/router';

export const myFeatureRoutes: Route[] = [
  {
    path: '',
    title: 'My Feature',
    loadComponent: () => import('./my-feature/my-feature').then((m) => m.MyFeature),
    providers: [MyFeatureStore],
  },
];

Export the routes from the lib's barrel (libs/my-feature/src/index.ts):

export * from './lib/lib.routes';
// export * from './lib/my-feature.store';  // export the store too if needed

Components do not need to be in the barrel unless something outside the lib imports them directly. The routes are all that the remote entry point and the test stub need.

Step 2 – Install the MF package (if not already present)

pnpm add -D @module-federation/vite

@module-federation/vite is a build-time bundler plugin — it belongs in devDependencies.

Step 3 – Configure the remote's vite.config.ts

Copy apps/counter-remote/vite.config.ts as your starting point. After copying, update these remote-specific values:

Two required workaround plugins (always include both)

// 1. @module-federation/vite crashes when server.watch is boolean false
//    (Vite 8 + Nx sets this by default). Must run pre-enforce.
{
  name: 'normalize-server-watch',
  enforce: 'pre' as const,
  config: () => ({ server: { watch: {} } }),
},

// 2. virtual:pwa-register is provided by VitePWA in the host only.
//    The remote must stub it so shared lib pre-transforms don't fail.
{
  name: 'virtual-pwa-register-stub',
  resolveId: (id: string) =>
    id === 'virtual:pwa-register' ? '\0virtual:pwa-register' : undefined,
  load: (id: string) =>
    id === '\0virtual:pwa-register'
      ? 'export const registerSW = () => () => {};'
      : undefined,
},

Disable federation in test mode

mode !== 'test' &&
  federation({
    name: 'my-remote',
    filename: 'remoteEntry.js',
    dts: false,
    exposes: {
      './Routes': './src/remote-routes.ts',
    },
    shared: sharedDeps,
  }),

Federation must be disabled in mode === 'test' — the MF virtual modules break vitest's module resolver.

External pwa-register from the build

build: {
  rolldownOptions: {
    external: ['virtual:pwa-register'],
  },
},

sharedDeps for the remote — import: false on CDK/Material

Critical: Angular CDK and Material packages must have import: false on the remote (not on the host). Without this, @module-federation/vite generates a loadShare virtual module with a top-level import * as __mfLocalShare from '@angular/material/button'. This eagerly evaluates the module from the remote's dev server (a different URL), causing Angular to register the same component class twice → NG0912 collisions at runtime.

With import: false, MF generates a deferred-export module that reads Material from the host's shared scope (__mfModuleCache) instead of loading its own copy.

// Use the exact versions from package.json (pnpm outdated to check)
const angVer = '~21.2.15';
const cdkMatVer = '~21.2.13';

const sharedDeps = {
  // Angular core — no import:false needed
  '@angular/animations': { singleton: true, requiredVersion: angVer },
  '@angular/common': { singleton: true, requiredVersion: angVer },
  '@angular/common/http': { singleton: true, requiredVersion: angVer },
  '@angular/compiler': { singleton: true, requiredVersion: angVer },
  '@angular/core': { singleton: true, requiredVersion: angVer },
  '@angular/forms': { singleton: true, requiredVersion: angVer },
  '@angular/platform-browser': { singleton: true, requiredVersion: angVer },
  '@angular/platform-browser/animations': { singleton: true, requiredVersion: angVer },
  '@angular/platform-browser-dynamic': { singleton: true, requiredVersion: angVer },
  '@angular/router': { singleton: true, requiredVersion: angVer },

  // CDK sub-paths — import:false prevents NG0912 (see note above)
  '@angular/cdk/a11y': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/cdk/bidi': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/cdk/layout': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/cdk/observers': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/cdk/overlay': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/cdk/portal': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/cdk/scrolling': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/cdk/text-field': { singleton: true, requiredVersion: cdkMatVer, import: false },

  // Material sub-paths — import:false for same reason
  '@angular/material/badge': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/bottom-sheet': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/button': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/checkbox': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/core': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/divider': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/form-field': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/icon': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/input': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/list': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/paginator': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/progress-spinner': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/sidenav': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/snack-bar': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/table': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/toolbar': { singleton: true, requiredVersion: cdkMatVer, import: false },
  '@angular/material/tooltip': { singleton: true, requiredVersion: cdkMatVer, import: false },

  // NgRx + utilities
  '@ngrx/signals': { singleton: true, requiredVersion: '~21.1.0' },
  '@ngrx/signals/events': { singleton: true, requiredVersion: '~21.1.0' },
  rxjs: { singleton: true, requiredVersion: '~7.8.2' },
  tslib: { singleton: true, requiredVersion: '~2.8.1' },
};

Add only the CDK/Material sub-paths your remote actually uses. If the remote later adds more Material imports, add their sub-paths here too.

Do NOT add @myorg/* workspace libs to the shared config. MF uses Rolldown to build loadShare virtual modules, and Rolldown cannot enumerate export * chains from TypeScript path aliases. This causes [MISSING_EXPORT] build errors at runtime. Workspace libs should be bundled into the remote directly.

Use sub-paths, not root paths. Declaring '@angular/material': { ... } (no trailing slash) only matches the exact bare specifier. It does NOT match @angular/material/button. You must list each sub-path explicitly.

Step 4 – Configure the host's vite.config.ts

Add the remote to the host's federation config. The host's sharedDeps does not need import: false — the host is the provider of these

Content truncated.