feat(tanstack): add browser federation coverage across hosts

- Make Rsbuild SSR federation opt-in and eager React host shares
- Add browser tests for hydration, remote interaction, and offline fallbacks
- Document support boundaries and update release workflows

Author: Nsttt

.github/workflows/ci.yml

@@ -34,5 +34,6 @@ jobs:
       - run: pnpm format:check
       - run: pnpm typecheck
       - run: pnpm build
+      - run: pnpm exec playwright install --with-deps chromium
       - run: pnpm test
       - run: pnpm pack:tanstack

.github/workflows/release.yml

@@ -66,6 +66,7 @@ jobs:
       - run: pnpm format:check
       - run: pnpm typecheck
       - run: pnpm build
+      - run: pnpm exec playwright install --with-deps chromium
       - run: pnpm test
       - run: pnpm pack:tanstack
       - name: Compute dist-tag

README.md

@@ -48,15 +48,17 @@ export default defineConfig({
 ```
 
 Defaults are `remoteEntry.js`, `manifest: true`, and
-`hostInitInjectLocation: "entry"`. React and `react-dom` are shared singleton
-defaults; any explicit entries in `shared` take precedence.
+`hostInitInjectLocation: "entry"`. React and `react-dom` are shared
+singletons; when the config declares `remotes`, they are also eager so the
+host's own React stays in the share scope. Explicit entries in `shared` take
+precedence.
 
 Do not set a global Module Federation `target`. TanStack Start builds client
 and SSR environments from one Vite configuration, so the wrapper leaves target
 selection to `@module-federation/vite` for each environment.
 
 The package supports Node 22.18+, 24.11+, and 26+, plus Vite 7/8 and TanStack
-Start 1.x. Use Vite 8 when developing SSR hosts that load remotes; Vite 7
+Start 1.167.43+. Use Vite 8 when developing SSR hosts that load remotes; Vite 7
 remains supported for production builds.
 
 The package root remains a Vite compatibility export. New Vite projects can
@@ -75,35 +77,47 @@ export default defineConfig({
     ...tanstackStartModuleFederation({
       federation: {
         name: "host",
+        shareStrategy: "loaded-first",
         remotes: { remote: "remote@https://example.test/mf-manifest.json" },
       },
     }),
   ],
 });
 ```
 
-The Rsbuild adapter registers browser and SSR federation plugins by default. It
-emits script-compatible browser output and async-node CommonJS SSR output so
-its manifest can be consumed by Vite and Rsbuild hosts. The wrapper adds eager,
-singleton `react` and `react-dom` entries without changing the caller's config
-object. Set `server: false` for browser-only remotes.
+The Rsbuild adapter emits script-compatible browser output, so its manifest can
+be consumed by Vite and Rsbuild hosts. It adds eager, singleton `react` and
+`react-dom` entries without changing the caller's config object. Hosts should
+use `shareStrategy: "loaded-first"` so one offline remote cannot fail startup.
 
-Server federation mode emits `dist/server/index.cjs`; browser-only mode keeps
-TanStack Start's standard `dist/server/index.js` entry.
+SSR federation for Rsbuild is experimental and opt-in: `server: true` adds an
+async-node CommonJS server container and changes the server entry to
+`dist/server/index.cjs`.
 
-## Example
+## Support status
 
-The workspace includes Vite and Rsbuild pairs. `apps/vite-remote` exposes a
-stateful React card to `apps/vite-host`. `apps/rsbuild-remote` exposes a second card
-to the Vite host, while `apps/rsbuild-host` consumes the Vite remote. Both
-cross-bundler links use manifest URLs. They render after hydration, so this is
-browser interop coverage, not an unverified SSR interoperability claim.
+| Host    | Remote  | Browser federation | Federated SSR                 |
+| ------- | ------- | ------------------ | ----------------------------- |
+| Vite    | Vite    | Supported          | Supported                     |
+| Vite    | Rsbuild | Supported          | Not supported                 |
+| Rsbuild | Vite    | Supported          | Not supported                 |
+| Rsbuild | Rsbuild | Supported          | Experimental (`server: true`) |
+
+[`TODO.md`](TODO.md) tracks the remaining SSR work.
+
+## Examples
+
+The workspace has four TanStack Start apps; see [`apps/README.md`](apps/README.md).
 
 ```bash
 pnpm install
 pnpm start
 ```
 
-This starts all four applications so both same-bundler and cross-bundler paths
-are available. Open the Vite host at http://localhost:3000 or the Rsbuild host
-at http://localhost:3003.
+Open the Vite host at http://127.0.0.1:3000 or the Rsbuild host at
+http://127.0.0.1:3003. Each host renders a card from both remotes.
+
+`pnpm test` builds everything, starts all four apps, and drives both hosts in
+headless Chromium. It checks hydration, remote interactivity, console errors,
+and the fallback when a remote is offline. Run
+`pnpm exec playwright install chromium` once before the first local test run.

TODO.md

@@ -3,7 +3,9 @@
 This file tracks the work required before `@module-federation/tanstack` can
 claim SSR support across both Vite and Rsbuild/Rspack.
 
-Assessment date: 2026-09-18.
+Assessment date: 2026-09-18. Updated 2026-10-06: the Rsbuild server adapter is now
+opt-in (`server: true`), and browser tests cover hydration, shared React
+identity, and remote outages for every host/remote pair.
 
 ## Current support boundary
 
@@ -12,11 +14,11 @@ Assessment date: 2026-09-18.
 | Vite    | Vite    | Supported            | The Vite host response contains remote markup before hydration.                 |
 | Vite    | Rsbuild | Not supported        | The Rsbuild remote loads in the browser after hydration.                        |
 | Rsbuild | Vite    | Not supported        | The Vite remote loads through the browser runtime after hydration.              |
-| Rsbuild | Rsbuild | Not yet supported    | The adapter can build a server container, but no end-to-end SSR fixture exists. |
+| Rsbuild | Rsbuild | Experimental         | `server: true` builds a server container, but no end-to-end SSR fixture exists. |
 
 The Rsbuild examples are TanStack Start SSR applications, so their local route
-shells render on the server. Their Module Federation configuration passes
-`server: false`; federated components are client-only. Do not describe that as
+shells render on the server. Their Module Federation configuration uses the
+default browser-only mode; federated components are client-only. Do not describe that as
 federated SSR.
 
 The supported claim today is:
@@ -70,8 +72,8 @@ Reference implementation paths:
 - Core only installs its startup dependency handling when
   `experiments.asyncStartup` is enabled. The TanStack adapter does not default
   this option today.
-- Both committed Rsbuild examples pass `server: false`, so the server adapter is
-  covered by compiler-contract tests, not by a running host/remote pair.
+- Both committed Rsbuild examples use the default browser-only mode, so the
+  server adapter is covered by compiler-contract tests, not by a running host/remote pair.
 
 Reference implementation paths:
 
@@ -231,7 +233,7 @@ This aligns the host with the existing Rsbuild server output.
 
 | Host      | Remote    | Development  | Production | Initial remote HTML | Hydration and interaction |
 | --------- | --------- | ------------ | ---------- | ------------------- | ------------------------- |
-| Vite 8    | Vite 8    | Existing     | Existing   | Existing            | Add browser assertion     |
+| Vite 8    | Vite 8    | Existing     | Add        | Existing            | Existing (development)    |
 | Vite 7    | Vite 7    | Not required | Add        | Add                 | Add                       |
 | Rsbuild 2 | Rsbuild 2 | Add          | Add        | Add                 | Add                       |
 | Vite 8    | Rsbuild 2 | Add          | Add        | Add                 | Add                       |
@@ -258,7 +260,7 @@ Each matrix row must verify:
 
 - [ ] Update the root README only after a matrix row satisfies every acceptance
       criterion.
-- [ ] Document `server: false` as browser-only federation, not SSR federation.
+- [x] Document browser-only federation as the Rsbuild default and SSR as opt-in.
 - [ ] Document `dist/server/index.cjs` when the CommonJS Rsbuild server adapter
       is enabled.
 - [ ] Document the chosen cross-bundler server-entry format.
@@ -283,3 +285,15 @@ SSR support for a host/remote combination is complete only when:
 
 Until then, keep the package description precise: Vite-to-Vite SSR is supported;
 Rsbuild and cross-bundler SSR are in progress.
+
+## Example and development gaps
+
+- [ ] Run the browser tests against production builds, not only development
+      servers.
+- [ ] A Vite remote with `exposes` does not hydrate when opened directly in
+      development: `@module-federation/vite` 1.22 forces host-driven init for
+      exposing containers (`forceClientInjected`). Report upstream, or add a
+      standalone init path.
+- [ ] Decide whether the Rsbuild adapter should default hosts to
+      `shareStrategy: "loaded-first"`. With `version-first`, one offline remote
+      fails host startup with `RUNTIME-003`; the example sets it explicitly.

apps/README.md

@@ -1,28 +1,50 @@
 # TanStack Start examples
 
-Both sides of this example are TanStack Start applications.
+Four TanStack Start applications: a host and a remote for each bundler. Each
+host consumes both remotes, so every host/remote combination runs.
 
-- `vite-remote` exposes `./StatusCard` from its Module Federation container and also
-  renders the component on its own `/` route.
-- `vite-host` loads `tanstack_vite_remote/StatusCard` from the remote running on
-  port 3001. Its own application runs on port 3000.
+| App              | Port | Role                                                                   |
+| ---------------- | ---- | ---------------------------------------------------------------------- |
+| `vite-host`      | 3000 | Server-renders the Vite remote; loads the Rsbuild remote on the client |
+| `vite-remote`    | 3001 | Exposes `./StatusCard`, rendered into the Vite host's initial HTML     |
+| `rsbuild-remote` | 3002 | Exposes `./StatusCard` through a browser manifest                      |
+| `rsbuild-host`   | 3003 | Loads both remotes with `loadRemote()` after hydration                 |
 
 From the repository root:
 
 ```bash
 pnpm start
 ```
 
-The federation wrapper must precede `tanstackStart()` in both Vite configs.
-React and React DOM use the wrapper's singleton defaults.
-
-Each package's `start` script runs Vite's development server. In Vite's CLI,
-the bare `vite` command means “start”; the literal `vite start` command would
-treat `start` as a project directory.
-
-`rsbuild-remote` exposes the same kind of card through Rspack with a browser
-manifest. Both hosts consume both remotes by manifest URL after hydration.
-These examples exercise same-bundler and cross-bundler client interoperability;
-they do not claim that cross-bundler SSR remote rendering is supported.
-
-`pnpm start` runs all four applications on ports 3000 through 3003.
+Then open http://127.0.0.1:3000 or http://127.0.0.1:3003. Every remote card has
+a counter button; clicking it proves the remote shares the host's React
+instance.
+
+## What each host shows
+
+- **Vite host.** The route loader imports the Vite remote, so its card is in
+  the server response ("Rendered on the server") and hydrates in place. The
+  Rsbuild card mounts after hydration. Both remotes sit behind
+  `RemoteBoundary`, an error boundary with a fallback card, so a failed remote
+  never blanks the page.
+- **Rsbuild host.** `RemoteCardSlot` calls `loadRemote()` in an effect and
+  shows "Remote unavailable" when a remote fails. The host uses
+  `shareStrategy: "loaded-first"`, so it does not fetch every remote's
+  manifest at startup.
+
+Stop the Rsbuild remote while both hosts are open and reload them: each host
+keeps rendering and shows its fallback card.
+
+## Notes
+
+- The federation wrapper must come before `tanstackStart()` in the Vite
+  configs.
+- Each `start` script runs the bundler's development server. In Vite's CLI the
+  bare `vite` command starts the dev server; `vite start` would treat `start`
+  as a project directory.
+- In development, opening the Vite remote directly (port 3001) server-renders
+  the page but does not hydrate: `@module-federation/vite` waits for a host to
+  initialize a container that has `exposes`. It hydrates when loaded through a
+  host, and its production build hydrates standalone.
+- Cross-bundler remotes render on the client only. Cross-bundler SSR is not
+  supported yet.

apps/rsbuild-host/rsbuild.config.ts

@@ -13,12 +13,13 @@ export default defineConfig({
       federation: {
         dts: false,
         name: "tanstack_rsbuild_host",
+        // Resolve remotes on demand so one offline remote cannot block host startup.
+        shareStrategy: "loaded-first",
         remotes: {
           tanstack_vite_remote: "tanstack_vite_remote@http://127.0.0.1:3001/mf-manifest.json",
           tanstack_rsbuild_remote: "tanstack_rsbuild_remote@http://127.0.0.1:3002/mf-manifest.json",
         },
       },
-      server: false,
     }),
   ],
 });

apps/rsbuild-remote/rsbuild.config.ts

@@ -18,7 +18,6 @@ export default defineConfig({
         exposes: { "./StatusCard": "./src/components/StatusCard.tsx" },
         name: "tanstack_rsbuild_remote",
       },
-      server: false,
     }),
   ],
 });

apps/vite-host/src/components/RemoteBoundary.tsx

@@ -0,0 +1,28 @@
+import { Component, Suspense, type ReactNode } from "react";
+
+type Props = { children: ReactNode; fallback: string; name: string };
+
+/** Keeps a failed remote from taking down the host route. */
+export class RemoteBoundary extends Component<Props, { failed: boolean }> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: unknown) {
+    console.warn(`[${this.props.name}] remote failed to render`, error);
+  }
+
+  render() {
+    if (this.state.failed) {
+      return <div className="remote-loading">{this.props.name} is unavailable</div>;
+    }
+
+    return (
+      <Suspense fallback={<div className="remote-loading">{this.props.fallback}</div>}>
+        {this.props.children}
+      </Suspense>
+    );
+  }
+}

apps/vite-host/src/routes/index.tsx

@@ -1,5 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { lazy, Suspense, useEffect, useState } from "react";
+import { lazy, useEffect, useState } from "react";
+import { RemoteBoundary } from "../components/RemoteBoundary";
 
 const RemoteStatusCard = lazy(() => import("tanstack_vite_remote/StatusCard"));
 const RsbuildStatusCard = lazy(() => import("tanstack_rsbuild_remote/StatusCard"));
@@ -16,8 +17,8 @@ function Home() {
         <p className="eyebrow">TanStack Start × Module Federation</p>
         <h1>Two full-stack apps. One React tree.</h1>
         <p className="lede">
-          This page belongs to the Vite host on port 3000. The interactive card below is owned and
-          built by a second TanStack Start application on port 3001.
+          This page belongs to the Vite host on port 3000. The Vite remote on port 3001 renders its
+          card on the server; the Rsbuild remote on port 3002 loads in the browser after hydration.
         </p>
       </header>
 
@@ -29,9 +30,9 @@ function Home() {
           <p>The route, document shell, and server response come from the host app.</p>
         </article>
 
-        <Suspense fallback={<div className="remote-loading">Loading the remote app…</div>}>
+        <RemoteBoundary fallback="Loading the remote app…" name="Vite remote">
           <RemoteStatusCard />
-        </Suspense>
+        </RemoteBoundary>
 
         <RsbuildRemoteSlot />
       </section>
@@ -49,8 +50,8 @@ function RsbuildRemoteSlot() {
   if (!mounted) return <div className="remote-loading">Rsbuild remote loads after hydration</div>;
 
   return (
-    <Suspense fallback={<div className="remote-loading">Loading the Rsbuild remote…</div>}>
+    <RemoteBoundary fallback="Loading the Rsbuild remote…" name="Rsbuild remote">
       <RsbuildStatusCard />
-    </Suspense>
+    </RemoteBoundary>
   );
 }

docs/RELEASING.md

@@ -4,7 +4,7 @@ summary: Release and trusted npm publishing for @module-federation/tanstack.
 read_when:
   - Preparing a release
   - Updating release automation
-updated_at: 2026-09-16
+updated_at: 2026-10-06
 ---
 
 # Releasing
@@ -41,8 +41,12 @@ The publish workflow reruns the gate, checks that the source is reachable from
 a different dist-tag. Configure npm trusted publishing for repository
 `module-federation/tanstack`, workflow `release.yml`, environment `Publish`.
 
-The release gate builds the Vite and Rsbuild example pairs. It checks the Vite
-Vite host server bundle and both directions of client manifest interoperability. The
-Rsbuild example remote is browser-only; package tests cover the adapter's
-async-node CommonJS SSR configuration. Browser-level coverage for hydrated
-cross-bundler rendering remains follow-up work.
+The release gate builds the Vite and Rsbuild example pairs and checks their
+manifests and server bundles. It then starts all four apps and drives both hosts
+in headless Chromium: Vite-to-Vite SSR markup, hydration, remote interactivity,
+one shared React instance, no console errors, and the fallback when a remote is
+offline. Package tests cover the opt-in Rsbuild async-node CommonJS SSR
+configuration.
+
+The test suite needs Chromium. Locally, run `pnpm exec playwright install
+chromium` once; the workflows install it before `pnpm test`.