Local development with micro-frontends

Developers should be able to work on one remote without running the whole platform. Good local development means one command, a fast start and a realistic environment.

The goal

A developer in the orders team changes orders. Their machine should run the orders remote and as little else as possible. If working on one area requires cloning and starting every repository, the platform has made daily work slower than it was in the monolith.

There are two useful modes, and a mature platform offers both.

Mode 1: Standalone, with a mock of the host

The remote runs alone as a normal application. A thin development shell replaces the real host and provides what the contract promises:

• A fake session with a configurable user, roles and locale.
• A minimal layout, so the remote renders at realistic sizes.
• The design system theme.
• Stubs for the navigation and event APIs, with logging so the developer sees what the remote sends.

The platform team should publish this development shell as a package, versioned together with the contract. If each team writes its own mock, the mocks drift away from the real host and bugs appear only after a deploy.

Standalone mode is the fastest, and it is the right one for most daily work and for the remote's own tests. Its limit is realism: it shows nothing about how the remote behaves next to its real neighbours.

Mode 2: Local remote against deployed versions of the rest

Here the developer runs only their remote locally. The host and all other remotes come from a deployed environment. This shows the real integration without the cost of running everything.

Common ways to do it:

• Local host with a development manifest. The host runs locally with a manifest in which every remote points to the deployed development environment, except the one being changed, which points to localhost.
• Deployed host with an override. The developer opens the deployed host of a development environment and tells it to load one remote from localhost. Platforms based on import maps often use the import-map-overrides library for this. A custom host can support the same idea with a value in local storage that only non-production builds honour.
• Workspace tooling. In an Nx workspace with Module Federation, the serve command of the host accepts a list of remotes to run in development mode and serves the others as static builds.

Two conditions apply. The local remote must allow cross-origin requests from the host's origin. And its shared dependency versions must be compatible with the deployed ones: a local branch that upgrades the framework may fail to load inside a host that still uses the previous version, or may load a second copy of the framework.

Environment configuration

Configuration is where local setups usually break.

• Use runtime configuration. Load API addresses and feature flags from a small configuration file at startup, and avoid baking them into the build. The same build can then run locally, in test and in production.
• Proxy API calls. The development server can forward API requests to a shared development backend, which avoids cross-origin problems. The Angular CLI supports this through a proxy configuration file.
• Plan authentication for localhost. The identity provider needs a development client that accepts local redirect addresses. In standalone mode, the mock session avoids the login entirely.
• Mock the backend when needed. A tool such as Mock Service Worker lets a remote run with no backend, which helps in early work and gives stable tests.

Keeping startup fast

Speed decides whether people follow the intended workflow or invent shortcuts.

• Run only what you change. Everything else comes prebuilt, from a deployed environment or from a cache.
• Prefer fast builders. Recent Angular versions build with esbuild, and Native Federation works on top of that builder. The differences are covered in Module Federation vs Native Federation.
• Expect limits in hot reload. Hot module replacement across federated modules is less reliable than in a single app. A full reload of a small remote is usually fast enough.

One command and a short document

Each remote's repository should offer:

1. One command that starts standalone mode.
2. One command that starts the remote against the development environment.
3. A short README: prerequisites, the two commands, how to log in, how to choose the mock user.

A new engineer should be able to run their remote on the first day. If that takes longer, the platform team has work to do.

More in this section

• What are micro-frontends? A plain guide for decision makers
• When micro-frontends are worth it, and when they are not
• Module Federation vs Native Federation for Angular
• single-spa vs Module Federation: how to choose