mfe-skills / rules

---
description: MFE boundary review: MFE boundary rules — critical (rules 3 and 4). Load when this topic is in scope; part of mfe-skills.
alwaysApply: false
---

# MFE boundary rules — critical (rules 3 and 4)

## Contents

- Rule 3 — Hides implementation details behind an API contract
- Rule 4 — Communicates via events, not shared state

**Version**: 1.3 | **Skill**: reviewing-mfe-boundaries | **Source**: *Building Micro-Frontends* (O'Reilly).

Critical rules: hide implementation details; communicate via events not shared state.
For rules 1, 2, 5–8 and governance extensions: load `references/rules-core-standard.md`.
For framework-specific patterns: load `references/rules-toolchain.md`.

---

## Rule 3 — Hides implementation details behind an API contract

Define the API contract upfront between producer and consumer teams. Internal implementation details — frameworks, data fetching strategies, database schemas, code structure — stay hidden behind it.

**The API-first principle**: the contract is the binding agreement. Both teams can work in parallel, focused on their side of the contract. Either team can change their internals freely without affecting the other, as long as the contract is respected.

**Strong encapsulation is required** to avoid domain leaks into other parts of the application. When a micro-frontend exposes its internals — through direct imports, shared modules, or coupled data structures — changes inside cascade outside and independent deployment breaks down.

**Violation signals**:
- Direct imports from one micro-frontend's source into another
- Shared internal modules or utilities across micro-frontend boundaries
- Contract changes that require simultaneous updates across multiple teams
- A micro-frontend exposing more than what consumers strictly need

**Code-checkable patterns**:
```javascript
// ✗ CRITICAL — cross-boundary import, bypasses the API contract
import { UserStore } from '@org/auth-mfe/store'
import { useCart } from '@org/cart-mfe/hooks'
import { formatCurrency } from '@org/checkout-mfe/utils'

// ✓ Each micro-frontend accesses only its own internals
import { formatCurrency } from './utils/currency'

// ✓ Shared utilities belong in an npm package, not a micro-frontend
import { formatCurrency } from '@org/shared-utils'
```

**Aliased imports do not fix this**: `import { UserStore as Store } from '@org/auth-mfe/store'` is still a Rule 3 violation. The coupling exists at the resolved module level regardless of the local alias.

---

## Rule 4 — Communicates via events, not shared state

Micro-frontends must remain decoupled from each other. A global state manager shared across micro-frontends is an anti-pattern in distributed systems.

**Three channels — do not mix them up:**

| Channel | Who listens | Allowed events | Example |
|---------|-------------|----------------|---------|
| **Shell platform bus** | Shell only | `shell:alert`, `shell:modal:open`, `shell:toast` | MFE asks shell to show a modal |
| **Peer bus (horizontal split)** | Other MFEs on the same page | Domain namespaces (`catalog:*`, `checkout:*`) | Basket reacts to `catalog:itemAdded` |
| **URL / storage (vertical split)** | Owning MFE via URL or storage | N/A — use paths and tokens | `/catalog/product/sku-1`, `sessionStorage` auth token |

**Shell must not** subscribe to domain events (`catalog:productSelected`, `checkout:completed`). Those belong to peer MFEs or to URL/storage across views.

**For cross-view communication (vertical split)**:
- Prefer **URL** (first segment changes area; deeper paths stay in the owning MFE)
- Use **web storage** or **cookies** for auth tokens
- Never pass complex domain objects between views

**Violation signals**:
- Shared Redux, Zustand, or MobX store across micro-frontend boundaries
- `window.__mfe_*` or shell-owned global singletons holding domain data
- Shell `useEffect` handlers for `catalog:*`, `checkout:*`, or similar domain namespaces
- Props drilling domain objects or using callbacks as the primary coordination mechanism

**Code-checkable patterns**:
```javascript
// ✗ CRITICAL — shared store across boundaries
import { checkoutStore } from '@org/checkout-mfe/store'

// ✗ CRITICAL — shell listens to domain events
platformBus.on('catalog:productSelected', handler)  // in shell App.tsx

// ✓ MFE → shell platform chrome
platformBus.emit('shell:alert', { message: 'Saved', variant: 'success' })

// ✓ Horizontal peers — domain events (not handled by shell)
eventBus.emit('catalog:itemAdded', { productId })

// ✓ Vertical split — URL
window.location.href = `/catalog/product/${productId}`
```

**Callback anti-pattern** (less severe but flag it):
```jsx
// ✗ Callbacks as primary coordination mechanism — brittle coupling
<CheckoutMicrofrontend
  onUserDataNeeded={(cb) => cb(userData)}
  onCartUpdate={(data) => updateParentCart(data)}
/>
```

---

---