Federated State Done Right: Zustand, TanStack Query, and the Patterns That Actually Work · NextSteps Blog
module-federationreactmicro-frontends
Federated State Done Right: Zustand, TanStack Query, and the Patterns That Actually Work
Martin Rojas
♦♦11 min read
Zustand and TanStack Query patterns that actually work in Module Federation. Singleton configuration, cache sharing, and production-tested micro-frontend state.
We've all been there: you set up Module Federation, split your app into micro-frontends, and suddenly your Zustand store updates in one module but not another. Or worse—your TanStack Query cache fetches the same user profile three times because each remote thinks it's alone in the world.
The patterns that work beautifully in monolithic React apps break down in federated architectures. Context providers don't cross module boundaries. Stores instantiate twice. Cache invalidation becomes a distributed systems problem you didn't sign up for.
This guide covers the patterns that actually work in production—singleton configuration that prevents duplicate instances, cache-sharing strategies that don't create tight coupling, and the critical separation between client state (Zustand) and server state (TanStack Query) that makes federated apps maintainable. These aren't theoretical recommendations; they're lessons from teams at Zalando, PayPal, and other organizations running Module Federation at scale.
Why Federated State Breaks: The Memory Model Problem
In a monolithic SPA, memory is a contiguous, shared resource. A Redux store or React Context provider instantiated at the root is universally accessible. In a federated system, the application is composed of distinct JavaScript bundles—often developed by different teams, deployed at different times, and loaded asynchronously at runtime. These bundles execute within the same browser tab, yet they're separated by distinct closure scopes and dependency trees.
The root cause of most Module Federation state issues is deceptively simple: without explicit singleton configuration, each federated module gets its own instance of React, Redux, or Zustand. Users experience this as authentication that works in one section but not another, theme toggles that affect only part of the interface, or cart items that vanish when navigating between micro-frontends.
The Share Scope Engine
The engine powering state sharing is the __webpack_share_scopes__ global object—an internal Webpack API that acts as a registry for all shared modules in the browser session.
When the Host application bootstraps, it initializes entries in __webpack_share_scopes__.default for every library marked as shared. Each entry contains the version number and factory function to load the module. When a Remote application initializes, it performs a handshake: inspecting the share scope, comparing available versions against its requirements, and using semantic versioning resolution to determine compatibility.
If the Host provides React 18.2.0 and the Remote requires ^18.0.0, the runtime determines compatibility and the Remote uses the Host's reference. This "Reference Sharing" ensures that when the Remote calls React.useContext, it accesses the exact same Context Registry as the Host. If this handshake fails, the Remote loads its own React, creating a parallel universe where the Host's providers don't exist.
Configuration for Singleton Enforcement
The fix requires explicit singleton configuration in webpack:
Three configuration properties matter most: singleton: true ensures only one instance exists across all federated modules, strictVersion: true throws errors when versions conflict rather than silently loading duplicates, and requiredVersion with explicit semver ranges prevents deployment failures. Dynamically loading versions from package.json ensures configuration matches installed packages.
The Async Boundary Pattern
The "Shared module is not available for eager consumption" error plagues new Module Federation setups. Standard entry points import React synchronously, but shared modules load asynchronously. The runtime hasn't initialized the share scope before the import executes.
Setting eager: true forces the library into the initial bundle, solving the error but adding ~100-150KB gzipped to Time to Interactive. The architectural best practice is establishing an asynchronous boundary:
// index.js - Simple wrapper enabling async loading
import('./bootstrap');
// bootstrap.js - Your actual application entry
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
ReactDOM.render(<App />, document.getElementById('root'));
When Webpack sees import('./bootstrap'), it creates a promise. During resolution, the Federation runtime initializes __webpack_share_scopes__, checks remote entry points, and ensures shared dependencies are ready. By the time bootstrap.js executes, React is available in the shared scope.
Client State: Zustand vs Redux in Federated Architectures
Zustand has emerged as the preferred client state library for micro-frontends due to its 1KB bundle size, singleton-friendly architecture, and absence of provider hierarchy requirements. Unlike Redux or Context, a Zustand store doesn't require wrapping components in providers that must align across module boundaries.
The "Initial Value Only" Bug
Developers migrating to federated architectures often encounter a baffling bug: the Remote application renders initial state correctly, but when the Host updates state, the Remote fails to re-render. It appears "stuck" on the initial value.
This highlights the difference between sharing code and sharing instances. If both Host and Remote import a store via build-time aliases, the bundler includes the code in both bundles. At runtime, the Host creates Store_Instance_A, the Remote creates Store_Instance_B. The Host updates Instance A; the Remote listens to Instance B. No update propagates.
The Exported Store Pattern
To guarantee synchronization, ensure the exact same JavaScript object in memory is used by both Host and Remote:
When remote/App.tsx imports host/CartStore, Webpack delegates loading to the Federation runtime, which returns the module reference the Host already loaded. The useCartStore refers to the exact closure created in the Host.
The Dependency Injection Pattern for Redux
For Redux-based architectures with Provider requirements, wrapping Remotes in their own <Provider store={store}> creates dangerous nested providers. A cleaner pattern is dependency injection:
// Remote declares store as a prop contract
interface Props {
store: StoreType;
}
const RemoteWidget = ({ store }: Props) => {
const state = useStore(store);
return <div>{state.value}</div>;
};
export default RemoteWidget;
// Host passes its store instance
const RemoteWidget = React.lazy(() => import('remote/Widget'));
const App = () => {
return (
<Suspense fallback="Loading...">
<RemoteWidget store={myStore} />
</Suspense>
);
};
This decouples the Remote from store location, enables testing with mock stores, and ensures ownership remains with the Host.
Server State: Cache Sharing Strategies
TanStack Query v5 fundamentally changed cache sharing by removing the contextSharing prop. The current approach requires explicit QueryClient sharing via Module Federation exposes.
Strategy A: Shared QueryClient (Monolithic Cache)
The Host initializes a single QueryClient and shares it:
Advantages: Instant cache deduplication—if the Host fetches ['user', 'me'] and the Remote needs the same data, TanStack Query serves it from cache without a network request. Global invalidation means mutations in one module update all consumers.
Risk: This requires successful Context sharing. If React instances differ, the Remote throws "No QueryClient set" errors.
Each Remote creates its own QueryClient, ensuring true independence.
Advantages: Remotes can use different React Query versions. A crash in the Host's cache doesn't affect Remotes.
Disadvantages: Both Host and Remote fetch the same data (double network traffic). If the Remote updates user data, the Host's cache remains stale until reload.
Feature
Shared QueryClient
Isolated QueryClient
Data Reuse
High (instant cache hits)
Low (relies on HTTP cache)
Coupling
Tight (must share React)
Loose (independent instances)
Invalidation
Global (one mutation updates all)
Local (manual sync required)
Robustness
Brittle (context issues fatal)
Robust (fail-safe)
Use When
Internal, trusted MFEs
3rd-party or distinct domains
Cross-MFE Cache Invalidation
For distributed caches requiring coordination, use BroadcastChannel:
TanStack DB, currently in beta, represents a paradigm shift from "Caching API Responses" to "Syncing a Database Replica." It's particularly transformative for distributed architectures because it solves synchronization at the protocol level.
State is organized into typed Collections rather than arbitrary string keys, acting as rigid contracts. Multiple MFEs can query the same dataset with different filters without coordinating who fetches what—the database acts as the central state hub.
For multi-tab synchronization, TanStack Query's broadcastQueryClient plugin provides a bridge:
Event-Driven Architecture: When State Isn't the Answer
Not all communication requires shared state. For transactional "fire-and-forget" interactions, events reduce coupling:
// Shared event bus
export const authChannel = new BroadcastChannel('auth_events');
export const sendLogout = () => {
authChannel.postMessage({ type: 'LOGOUT' });
};
// For same-document communication, use CustomEvent
window.dispatchEvent(new CustomEvent('cart:open', { detail: { productId } }));
CustomEvents leverage the browser's native event loop with zero library dependencies—ideal for UI signals like a "Buy Now" button triggering a cart drawer.
Combine with errorLoadRemote hooks for load fallbacks and React Error Boundaries for runtime errors.
Memory Leak Prevention
In federated architectures, MFEs mount and unmount as users navigate. Listeners registered on global stores or event buses that aren't cleaned up accumulate, causing duplicate API calls and unpredictable behavior. Strict linting enforcing cleanup functions in useEffect is mandatory.
Small teams (2-5 developers): Use Zustand + TanStack Query as singletons. Build-time sharing via Turborepo internal packages. Module Federation adds unnecessary complexity.
Medium teams (5-15 developers): Hybrid approach—shared packages for core functionality (auth, session), Module Federation for feature modules. Invest in three-layer error handling.
Large organizations (multiple teams): Props-based interfaces between MFEs, centralized authentication via shell, strict version alignment. Debugging distributed state exceeds coordination overhead.
The essential rule: Never store server data in client state libraries. TanStack Query handles caching, refetching, and invalidation—duplicating in Zustand creates synchronization bugs.
Production Checklist
Async boundary pattern (import('./bootstrap')) in every federated module entry
Singleton configuration for React, react-dom, and all state libraries with explicit requiredVersion
State logic extracted to shared libs/data-access packages
Host exposes state instances; Remotes consume via import from 'host/Store'
All event listeners return cleanup functions in useEffect
BroadcastChannel-based invalidation for cross-MFE coordination