MFE Platform ADR 009: Host runtime ownership

One host runtime, @gitlab/mfe-shell, mounts every micro-frontend on every surface; the monolith keeps only an adapter.

Context

ADR 003 §7 says that one Module Federation runtime serves every application on a page and that GitLab builds the injected clients; ADR 006 fixes what the host passes at mount time and how it refuses a mount. Neither says who owns the code that does this.

Left open, that question answers itself badly. Each surface that embeds a micro-frontend (an admin page, a page slot, a feature panel) would grow its own mounting code, each shaped like the first application that needed it, and the platform would have one contract on paper (ADR 006) and several in the code. Producers would then debug a different host in the monolith, in their local setup and in their tests.

Constraints

  • The same application must mount identically in the monolith, in a standalone development host, and in tests.
  • The monolith builds and serves with Rspack in production and in development, keeps a webpack 4 configuration as a fallback and Vite as an opt-in path, and tests with Jest; a host runtime cannot depend on one bundler’s federation plugin.
  • ADR 006’s refusal rules (unknown requirement, ungranted requirement, unknown or unavailable client, duplicate version) must be written in exactly one place, so that every host refuses the same way.
  • The monolith must not learn application names; a new application is a catalog entry, not a code change.

Decisions

1. @gitlab/mfe-shell is the only host runtime

The package @gitlab/mfe-shell (toolkit, ADR 004) owns everything between “the page has a mount element” and “the application’s mount(el, props) ran”:

  • the single Module Federation runtime per page, bundled into the package so that no host needs a federation plugin or a runtime dependency of its own;
  • registration of a remote from its manifest URL, including the dev-server and override sources of ADR 008;
  • the mount contract of ADR 006: building and freezing MountProps, lazy clients, capability checks, refusal codes, the .mfe-<name> class and the data-mfe-* state attributes on the mount element, and unmount;
  • the same behaviour in every host: the monolith, mfe-shell dev-host, and the test utilities the package ships for producers.

The package has no runtime dependencies, ships ES2019 output that every bundler the monolith uses can consume unchanged (the same target @gitlab/frontend-utils checks its build output against), and exposes its API through an exports map with a require build for Jest. A shared transpilation target for every toolkit package, instead of a target each package chooses, is a decision of its own for the toolkit; this package adopts it when it exists.

2. The monolith keeps an adapter, nothing more

The monolith’s own code about micro-frontends is reduced to an adapter that calls MfeShell.init once per page with the monolith’s instances: its HTTP client, its Apollo client, its error reporter and tracker, the user’s locale and theme, and the catalog entries the server rendered. The adapter contains no application names and no application-specific branches; it is the same code for every application the catalog lists. Surfaces that render a micro-frontend render a mount element with the server-resolved placement entry and let the shell do the rest.

The server and the shell share the rules, not the decision. Renderable.can_render? (ADR 008) is authoritative for whether a placement renders at all: it evaluates the refusal conditions against the catalog’s verified copy of the manifest, together with the permission words and the flags only the server can see, and a placement that fails is never rendered. The shell evaluates the same conditions once more, against the manifest the browser actually loaded, before any application code runs. That second pass is a backstop, not a second decision: it catches a dev server or an override whose manifest differs from the catalog’s copy, and it is the only check in a host that has no server (the development host, tests). The rules themselves are written once, in @gitlab/mfe-shell/contract, and the server’s check mirrors them; a refusal the shell raises on a page the server did render is reported through services.reportError with its refusal code, because it means the two copies disagree.

3. A seam for a build-time host

ShellOptions.runtimeFactory lets a host supply its own federation runtime instead of the bundled one. Tests use it today. It is also the way a future monolith that federates at build time (a bundler-level federation plugin in its own Rspack configuration) would plug in without a change to the mount contract or to any application. Until that host exists, nothing else uses the seam.

Alternatives considered

  • The monolith as a build-time Module Federation host. Not chosen now: it needs host configuration in the monolith’s Rspack build, and separately for its webpack fallback, its Vite path and Jest, with several behaviours to keep aligned. Kept reachable through runtimeFactory.
  • One federation runtime per application, no shared shell. Rejected: duplicate runtimes on a page, and no single place for the refusal rules of ADR 006.
  • Shipping the host runtime inside the monolith instead of a package. Rejected: the standalone development host and the producer test utilities would re-implement it, and producers could not pin the version they develop against.

Consequences

  • Producers develop against one package and see the same mount behaviour in the development host, in their tests and in production.
  • Any other host, another GitLab product or a page outside the monolith, is an adapter of the same shape: it supplies its own clients and catalog entries to MfeShell.init and gets every application unchanged.
  • A change to how applications are mounted is a package release with a version, reviewed in the toolkit, consumed by the monolith as a dependency bump; it is not a monolith change that each surface has to pick up.
  • The monolith’s diff for the platform is an adapter, mount elements and a dependency, not a federation configuration.
  • A build-time host, if ever wanted, is a runtimeFactory implementation, not a second contract.