This demonstrates how to use @tanstack/react-router in a Module Federation architecture, with Uniform providing CMS-driven composition and visual editing.
- Shared Uniform Components between micro-frontend modules
- Content lives in multiple projects for separation of teams
- Content editors get a visual preview experience
- A "host" project to bring all micro-frontend projects together
There are two applications and one shared package:
- Host (
/host) — the main application atlocalhost:5173 - Subapp (
/subapp) — a federated micro-frontend atlocalhost:5183, mounted under/subappin the host @repo/uniform-preview(/packages/uniform-preview) — a shared package that provides the Uniform server middleware, preview context, and composition API client
Both apps have their own TanStack Router and can run independently. In the host, the subapp's routeTree is loaded via module federation and merged into the host's route tree under a base path (/subapp).
- Subapp exposes its
routeTreeand aSubAppBannercomponent via@module-federation/vite - Host dynamically loads the subapp's route tree and registers it as a subtree (see ./host/src/utils/registerSubtree.tsx)
- A single router instance is used to avoid conflicts with browser history navigation
- Shared dependencies (
react,react-dom,@tanstack/react-router,@uniformdev/canvas,@uniformdev/canvas-react) are configured as singletons in the federation config
Remote loading is handled manually (see ./host/src/utils/loadRemote.ts) rather than using @module-federation/vite's built-in import syntax, so that a failed remote doesn't cause a blank page.
Uniform provides the content and layout for pages. Authors build compositions (pages) in the Uniform visual editor, and the frontend fetches and renders them using Uniform's SDK.
- TanStack Router catch-all routes (
$) call the composition API to fetch the Uniform composition for the current path - The composition data is passed to
<UniformComposition>which maps each componenttypeto a React component via aresolveComponentfunction - Each app has its own
resolveRendererthat maps Uniform component types (e.g.hero,page,siteHeader) to React components - Components use
<UniformSlot>for rendering child slots and<UniformText>/<UniformRichText>for inline-editable parameters
This shared package (/packages/uniform-preview) provides three entry points:
| Export | Description |
|---|---|
@repo/uniform-preview/vite |
setupUniformServer() — Vite dev server middleware that adds API endpoints for Uniform |
@repo/uniform-preview/react |
PreviewProvider and usePreview() — React context for managing preview/contextual editing state |
@repo/uniform-preview/api |
createCompositionApi() — factory that returns fetchComposition() and fetchCompositionById() methods |
Instead of a separate backend, Uniform's API layer runs as Vite dev server middleware. This is sufficient for this POC, in production you will need to replicate these API endpoints in your own API layer.
The setupUniformServer() function from @repo/uniform-preview/vite is registered as a Vite plugin in each app's vite.config.ts:
// host/vite.config.ts (simplified)
import { setupUniformServer } from "@repo/uniform-preview/vite";
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), "");
return {
plugins: [
// ... other plugins
{
name: "uniform-server",
configureServer(server) {
setupUniformServer(server, {
projectId: env.VITE_UNIFORM_PROJECT_ID,
apiKey: env.UNIFORM_API_KEY,
apiHost: env.UNIFORM_API_HOST,
edgeApiHost: env.UNIFORM_EDGE_API_HOST,
});
},
},
],
};
});This adds three middleware endpoints to the Vite dev server:
| Endpoint | Purpose |
|---|---|
/api/preview?app=...&secret=... |
Handles Uniform Canvas contextual editing redirects. When the Uniform visual editor opens a preview, this endpoint redirects to the correct frontend route with preview=true and compositionId query params. |
/api/composition?path=... |
Fetches a composition by its route path using RouteClient from @uniformdev/canvas. |
/api/composition-by-id?compositionId=...&state=... |
Fetches a composition by ID using CompositionDeliveryClient. Used during preview when the composition ID is known. |
The middleware also handles:
- CORS — allows requests from Uniform Canvas origins (
*.uniform.app) and configurable additional origins (used by the subapp to allow cross-MFE requests from the host) - Security headers — sets
X-Content-Type-OptionsandX-XSS-Protection - OPTIONS preflight — responds to CORS preflight requests on all
/api/routes
The PreviewProvider React context (from @repo/uniform-preview/react) manages the preview lifecycle:
- Detects preview mode, playground mode, and contextual editing mode from URL query parameters
- Listens for
postMessageevents from the Uniform Canvas iframe (uniform:composition:update) - Provides the current preview state via the
usePreview()hook so route loaders can decide whether to fetch published content or use the live preview composition
A playground route (/uniform-playground in the host) enables previewing Uniform Patterns (reusable component templates) within the app shell.
The subapp configures its composition API client to transform paths to strip its base path prefix:
// subapp/src/utils/uniform/composition.ts
const { fetchComposition, fetchCompositionById } = createCompositionApi({
apiBase: 'http://localhost:5183',
transformPath: (path) => path.replace('/subapp', '/'),
});The subapp's Vite config also includes allowedOrigins to permit cross-origin requests from the host.
Install with pnpm from the root:
pnpm iYou will need two Uniform projects, one for the host and one for the subapp.
Each app requires a .env file with Uniform credentials for it's project:
VITE_UNIFORM_PROJECT_ID=<your-project-id>
UNIFORM_PROJECT_ID=<your-project-id>
UNIFORM_API_KEY=<your-api-key>
UNIFORM_API_HOST=https://uniform.app
UNIFORM_EDGE_API_HOST=https://uniform.global
Push the latest component definitions and compositions to your Uniform project:
pnpm uniform:pushpnpm devOr run each application separately.
The host starts at http://localhost:5173.
The subapp starts at http://localhost:5183.
To use a different port, create a .env.development.local and override the PORT value.
We get around this by using a keepSingleSlot util to render the header and footer slots above and below the Subapp's Outlet.
See: examples/modulefederation-tanstackrouter/host/src/routes/__root.tsx
-------------------------
| HOST: Site Header | <= UniformComposition
-------------------------
| SUBAPP: Page | <= UniformComposition
-------------------------
| HOST: Site Footer | <= UniformComposition
-------------------------
Only the host can include UniformContext in a page. All optimisations from MFEs will need to be synced with the host project using the CLI.
The Canvas editor will show a warning when you are previewing a page from the Subapp in the host.