Skip to content

Issue

This is an important point that trips a lot of beginners. Let me clarify clearly:

Ports in a single Nx workspace

Even if all your apps (shell, assignments, watcher) are inside the same Nx workspace, you still need to assign each remote its own port when serving them.

  • Reason: Module Federation loads the remote via its remoteEntry.js URL. If two apps try to run on the same port, one will fail, and the host can’t load it.
  • Nx generators do not automatically assign unique ports for remotes; you need to specify them in the project.json or during serve commands.

Summary

  • Yes, you must assign a unique port for each remote, even if they’re in the same workspace.
  • Nx generators don’t automatically assign unique ports.
  • Host loads remotes using http://localhost:<port>/remoteEntry.js.
  • Without unique ports, the Module Federation host cannot find your remotes, leading to runtime errors.

Why it seems tricky

1. Multiple projects (host + remotes)

  • Each remote is basically its own React app with its own build config.
  • The host needs to know where and how to load each remote dynamically.

2. Webpack + Module Federation

  • You need to expose remote modules (./Module) and make the host load them via remoteEntry.js.
  • Ports must not conflict and configs must match your folder structure.

3. Executors / Nx configs

  • Nx v22+ uses specific executors for dev server, build, and module federation (@nx/react:module-federation-dev-server, @nx/webpack:webpack).
  • If versions don’t match or paths are wrong, things break in confusing ways.

4. TypeScript declarations

  • You often need remotes.d.ts in the host so TypeScript knows about remote modules.
host/src/remote.d.ts
// apps/shell/src/remote.d.ts
declare module "watcher/Module";
declare module "assignments/Module";

Now VSCode will stop showing the TS error. Runtime behavior does not change — Webpack Module Federation will load the remotes dynamically.

5. Caching & Nx Cloud

  • If not cleaned properly, Nx can cache old configs and throw errors like nx/src/utils/app-root not found.