Skip to content

Micro-Frontends: Team Boundaries in the Browser

Why the real work in micro-frontends is not the integration technique but the team split – shown with a runnable example landscape of a gateway, four applications and a component library.

≈ 10 min readSoftwareFrontend

Micro-Frontends: Team Boundaries in the Browser

Four teams, one index.html, one shared deployment per week. The math behind it looks harmless and is not: every release requires two days of code freeze, a regression round over the entire UI and four approvals. If one team is not done, three others wait. With fifty working weeks a year, that is at best fifty opportunities to ship something – and in practice far fewer, because a single failed smoke test holds back the entire release. Yet the backends of these teams have long been separate services with their own pipelines. In the browser, though, all four come together again in a single JavaScript bundle, and with the bundle returns exactly the bottleneck that splitting into services was supposed to remove.

An organizational problem with a technical symptom#

Micro-frontends are often discussed as a frontend topic: which framework, which integration technique, how small a fragment may be. Over the past few months, I have noticed that this discussion regularly misses the core. The real question is: Does the structure in the browser reflect the structure of the organization – or does it work against it? Conway’s observation from 1968 applies here too: systems mirror the communication paths of the organization that builds them. When four teams work separately by domain but maintain a shared single-page application, friction arises exactly at this seam – as merge conflicts in the router configuration, as coordination rounds over CSS classes, as a release calendar that becomes a permanent topic.

The pattern is not new. The ThoughtWorks Technology Radar has listed “Micro Frontends” since November 2016, and since May of this year in the “Trial” ring. With the Mosaic project and the layout service Tailor, Zalando has been running such an architecture in production for a good two years. What is new, at most, is the insight that comes when you rebuild it: the technical part is the easy one.

A runnable example landscape#

So as not to merely claim this, in July I put together the repository introduction-micro-frontends – a runnable example landscape with a gateway on port 7000 and, behind it, four standalone applications: Home (7010), Docs (7020), Products (7030) and Contact (7040), plus a catalog API, a GraphQL API on port 9000 and a shared component library on port 5000. Each application starts on its own, has its own build and could be run by its own team. The gateway knows the applications through a simple service discovery – from files, from Docker/Kubernetes or from Google Cloud, as you prefer – and routes by path.

flowchart LR
  B[Browser] --> G[Gateway<br/>:7000]
  G -->|/| H[home-app<br/>:7010<br/>Team A]
  G -->|/docs| D[docs-app<br/>:7020<br/>Team B]
  G -->|/products| P[products-app<br/>:7030<br/>Team C]
  G -->|/contact| C[contact-app<br/>:7040<br/>Team D]
  P --> Q[graphql-api<br/>:9000]
  H -. shared UI .-> L[components-library<br/>:5000]
  P -. shared UI .-> L

The diagram already shows the central design decision: the dividing lines run vertically. Each team owns a domain slice from the route to the API – not a horizontal layer such as “all buttons” or “all of the CSS.” This split is exactly what makes independent deployments possible in the first place; everything else is craftsmanship.

The easy part: integration#

The integration techniques are quickly listed, and none of them is spectacular.

The oldest is the hyperlink. If /products and /contact are separate applications, an <a href="/contact"> is enough – the browser loads the next page, the next team takes over. No shared code, no shared runtime, but a visible page change. For many transitions, that is entirely sufficient, and it is the only integration that is guaranteed never to break.

If fragments from different teams should appear on one page, you compose on the server side. Every nginx supports server-side includes out of the box:

# gateway: compose one page from team fragments
location / {
  ssi on;
  proxy_pass http://home-app:7010;
}

location /fragment/header {
  proxy_pass http://components-library:5000/header;
}
<!-- home-app: index.html -->
<!--#include virtual="/fragment/header" -->
<main>
  <!--#include virtual="/fragment/product-teaser" -->
</main>

Zalando’s Tailor takes the same principle further and streams fragments in parallel, with a timeout and fallback per fragment. Edge-side includes move composition into the Varnish or CDN layer. What all variants have in common: the page is built from independently deployable parts, and a slow fragment does not block the whole release, at most its own placeholder.

On the client side, Custom Elements are the cleanest bracket – native in Chrome and Safari since v1, in Firefox and Edge currently still via polyfill:

// products-app: expose a fragment as a custom element
class ProductTeaser extends HTMLElement {
  connectedCallback() {
    const sku = this.getAttribute('sku');
    fetch(`/products/api/teaser/${sku}`)
      .then((res) => res.text())
      .then((html) => { this.innerHTML = html; });
  }

  disconnectedCallback() {
    // team C cleans up its own listeners here
  }
}

customElements.define('product-teaser', ProductTeaser);

The receiving team writes <product-teaser sku="42"></product-teaser> and does not need to know which framework the fragment is built with internally. The DOM interface – attributes in, events out – is the contract between the teams. Then there are iframes: disreputable, but the only technique with complete isolation of CSS, JavaScript and global state. For a third-party payment form or a legacy module nobody wants to touch anymore, still a legitimate choice. And finally, single-spa orchestrates several framework applications within one single-page application – that solves the routing problem elegantly, but pulls all teams back into a shared runtime with a shared failure domain.

Which technique works is decided by a few questions:

  • How many page changes can the user flow tolerate – is a link enough?
  • Must the page deliver a usable first view without JavaScript (SSI, Tailor), or is the audience logged in anyway (client-side composition)?
  • How strictly must fragments be isolated – is naming discipline enough, or do you need the iframe boundary?
  • Who operates the composition point: a platform team running the gateway, or each team its own entry point?

Due diligence: routing, dependencies, CSS#

You still have to settle three things cleanly, or the monolith will catch up with you through the back door.

First, routing ownership. The URL is the public interface of the entire application, so it needs an owner. In the example repository, the gateway owns the top level – /products belongs to team C, completely, including all subpaths. As soon as two teams have to negotiate over a path, the split is drawn wrong. Deep links have to work like on any decent website: a reload on /products/42 lands at the right team without a central client router having to know about it. The gateway itself deliberately stays dumb – it knows paths and targets, but no domain logic. Every additional rule at this point turns it into the next shared deployment that everyone has to coordinate on again.

Second, shared dependencies. Four applications that each bundle their own React send the framework over the wire four times – with a library of a good 100 KB, that is measurable but rarely the end of the world. The alternative, a centrally mandated framework version for everyone, sounds more economical and costs more: every framework update becomes a four-team project again, and the shared release cadence is back. That is why in the repository, each application bundles for itself. I pay this price deliberately, because it is paid in kilobytes instead of meetings.

Third, CSS isolation. CSS has a global namespace, and in a composed page that is the gateway for action at a distance: team B changes a class .card, and team C’s layout shifts. Prefix conventions per team help immediately and cost nothing. Shadow DOM encapsulates styles completely, but depends on the same browser support as Custom Elements. The most reliable protection remains discipline: no global selectors, no element selectors, no !important across team boundaries.

The hard part: who owns the header?#

Up to this point, everything was technology, and technology can be tried out. The questions where such undertakings actually get stuck are not in any nginx configuration.

The header is the best example. It appears on every page, belongs to nobody in domain terms and to everybody technically. In one project, we played through three answers. A dedicated “header team” creates a new horizontal layer and thus a new bottleneck – every domain change becomes a ticket for another team. The second answer: one domain team owns the header, and all others embed it as a fragment. That works as long as this team takes the wishes of the others seriously – the header becomes an internal product with internal customers. The third answer is in the example repository: the header lives in the component library, versioned, and each team updates at its own pace. The price is honesty about reality – for a few days, two header versions are live at the same time. If you cannot live with that, you have decided against independent deployments and should call it that.

The design question has the same structure. A shared look and feel does not come from a central CSS file but from a styleguide that is maintained like a product: with versions, a changelog and contacts. Atomic Design provides a useful vocabulary for this – small, dumb building blocks are shared, composed views belong to the teams. The higher a component sits in this hierarchy, the more expensive it is to share.

What shared state costs#

The hardest currency is shared state. The standard example: on the product page, team C adds an item to the cart, and the mini cart in the header – owned by another team – should show the new count. The obvious reflex is a global store that all fragments read and write. With that, you bring back exactly the coupling you just got rid of: a shared state schema whose changes affect all teams at once, plus the question of whose version of the store gets loaded.

The cheaper answer: fragments do not share memory; they share events. The DOM brings the mechanism along, without any additional library:

// products-app: announce the change, share no memory
window.dispatchEvent(new CustomEvent('cart:item-added', {
  detail: { sku: '42', quantity: 1 }
}));

// header fragment: react and re-fetch its own truth
window.addEventListener('cart:item-added', () => {
  fetch('/cart/api/summary')
    .then((res) => res.json())
    .then((summary) => updateBadge(summary.count));
});

The header keeps its own state and fetches the truth from the cart API; the event is only the trigger. The contract between the teams shrinks to an event name and a small detail object – both can be documented and extended in a backward-compatible way.

The login status, the second perennial candidate for shared state, is a similar case. No fragment needs another team’s session object: a cookie on the shared domain, checked by the gateway, is enough as a shared fact – each fragment decides for itself what to show a logged-out visitor. Where that is not enough, for example for the display name in the header, a small API again provides the answer instead of a global object being passed through all fragments. Still: every such event is an interface, and interfaces need maintenance. When the list of cross-team events reaches double digits, that is not a tooling problem but a sign that the domain split is wrong – the teams are then long since working on the same thing, just against each other.

Bottom line#

The rule of thumb I take away from building the example landscape: you do not buy micro-frontends as a technology; you buy them as a form of organization – the technology can be learned in two weeks, the team split cannot. If you have only one frontend team, you do not need any of this; a well-structured monolith with clean module boundaries is then the more honest architecture. The rebuild becomes interesting when approval rounds, code freezes and release queues measurably cost time and several teams could actually deliver independently if you let them. Then it pays to settle the uncomfortable questions first – who owns the header, who maintains the styleguide, which events form the contract – and only then choose between SSI, Custom Elements and iframes. In the end, the integration technique is interchangeable. The team split it extends into the browser is not.

Further reading#

Revised and translated from German with the help of AI.