Common micro-frontend mistakes and how to avoid them
A small set of design and organizational mistakes shows up again and again in micro-frontend platforms. Each one is easy to recognize and has a known fix.
1. Splitting too small
What it looks like: a remote for the header, one for a search box, one for each widget. A single screen composes five or six remotes.
Why it hurts: every remote has a fixed cost in pipeline, monitoring, versions and load time. Small remotes pay that cost many times and gain nothing, because one team usually owns several of them and changes them together.
How to avoid it: split by business area with a team behind it. A remote should be large enough to deliver whole features alone. If you have more remotes than teams, merge some.
2. Shared mutable state
What it looks like: a global store that all remotes read and write, or objects on window that several areas modify.
Why it hurts: the state becomes a hidden interface. A change in its shape breaks other remotes at runtime, with no compiler to warn anyone. The order of releases starts to matter.
How to avoid it: each remote owns its state. Share only a small, read-only context from the host: user, permissions, locale. For everything else use navigation with parameters, a few versioned events and the backend as the source of truth. See communication between micro-frontends.
3. Coupled releases
What it looks like: a release calendar for the frontend, a shared staging environment that must be green for everyone, changes that only work if two remotes deploy on the same day.
Why it hurts: independent deployment is the reason for the architecture. Without it you have paid for a platform and kept the process of the monolith.
How to avoid it: make every change backward compatible with what is in production. Add before you remove: publish the new field or event, migrate the consumers, then delete the old one. Test each new version against the production versions of the others.
4. No design system
What it looks like: each team styles its own buttons, tables and forms. Spacing and behavior differ between areas. Users notice where one team's work ends.
Why it hurts: the product loses coherence, accessibility fixes have to be repeated in each remote, and every team spends time on the same basic components.
How to avoid it: start a shared design system before the second remote, even a small one: tokens, typography and the most used components. Give it an owner and a versioning policy. See design system across micro-frontends.
5. No ownership
What it looks like: remotes that everyone changes, a host maintained in spare time, alerts sent to a general channel. When something breaks, the first hour goes into finding who should look.
Why it hurts: code without an owner decays. The host in particular collects quick fixes from every team until nobody dares to change it.
How to avoid it: one owning team per remote, written down next to the route table. A platform team, or at least named people with assigned time, for the host, the pipeline templates and the contract. More in team ownership and Conway's law.
6. Version drift
What it looks like: remotes on three different versions of the framework and four of the design system. Upgrades are postponed because features come first.
Why it hurts: shared singletons stop working across incompatible versions. The runtime then loads duplicates, which costs performance, or fails with errors that are hard to diagnose. The longer the drift lasts, the harder the upgrade.
How to avoid it: set a policy with a window, for example that every remote must be on the current or the previous major version of the framework. Automate upgrade pull requests. Show the versions of every remote on a dashboard so drift is visible. Treat upgrades as planned work with time in each team's roadmap.
Other mistakes worth a mention
- A heavy host. Business logic in the shell means every team must change the shell. Keep it to layout, navigation, session and loading.
- No fallback when a remote fails. One broken deploy leaves a blank page. See error isolation and resilience.
- Choosing the architecture for one team. With a single team, the costs arrive and the benefits do not.
Summary
| Mistake | First sign | Fix |
|---|---|---|
| Splitting too small | More remotes than teams | Merge by business area |
| Shared mutable state | Runtime breaks after another team's release | Read-only context, events, backend |
| Coupled releases | A frontend release calendar | Backward compatible changes |
| No design system | Visible seams between areas | Small shared system with an owner |
| No ownership | Nobody answers an alert | One team per remote, a platform team |
| Version drift | Upgrades always postponed | Version window and automation |
Almost all of these are cheaper to prevent than to repair. Review this list when you design the platform, and again after the third remote is in production.
More in this section
- Micro-frontend readiness checklist
- Micro-frontend security: what changes and what to do
- Local development with micro-frontends
- What are micro-frontends? A plain guide for decision makers
Planning a migration or a micro-frontend platform?
In a 20-minute call you describe your situation and I tell you how I'd approach it. If it isn't worth doing yet, I'll say so.
Message me on LinkedIn