MFE Platform ADR 009: Host runtime ownership
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 thedata-mfe-*state attributes on the mount element, andunmount; - 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.initand 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
runtimeFactoryimplementation, not a second contract.
