feat(module-federation): support module federation in TanStack Start

e2e/react-start/basic/package.json

@@ -4,12 +4,12 @@
   "sideEffects": false,
   "type": "module",
   "scripts": {
-    "dev": "vite dev --port 3000",
-    "dev:e2e": "vite dev",
-    "build": "vite build && tsc --noEmit",
-    "build:spa": "MODE=spa vite build && tsc --noEmit",
-    "build:prerender": "MODE=prerender vite build && tsc --noEmit",
-    "preview": "vite preview",
+    "dev": "node scripts/run-bundler.mjs dev --port 3000",
+    "dev:e2e": "node scripts/run-bundler.mjs dev",
+    "build": "node scripts/run-bundler.mjs build",
+    "build:spa": "MODE=spa node scripts/run-bundler.mjs build",
+    "build:prerender": "MODE=prerender node scripts/run-bundler.mjs build",
+    "preview": "node scripts/run-bundler.mjs preview",
     "start": "node server.js",
     "test:e2e:startDummyServer": "node -e 'import(\"./tests/setup/global.setup.ts\").then(m => m.default())' &",
     "test:e2e:stopDummyServer": "node -e 'import(\"./tests/setup/global.teardown.ts\").then(m => m.default())'",
@@ -33,6 +33,8 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.50.1",
+    "@rsbuild/core": "^1.2.4",
+    "@rsbuild/plugin-react": "^1.1.0",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/router-e2e-utils": "workspace:^",
     "@types/js-cookie": "^3.0.6",

e2e/react-start/basic/rsbuild.config.ts

@@ -0,0 +1,49 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from '@rsbuild/core'
+import { pluginReact } from '@rsbuild/plugin-react'
+import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'
+import { isSpaMode } from './tests/utils/isSpaMode'
+import { isPrerender } from './tests/utils/isPrerender'
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url))
+
+const spaModeConfiguration = {
+  enabled: true,
+  prerender: {
+    outputPath: 'index.html',
+  },
+}
+
+const prerenderConfiguration = {
+  enabled: true,
+  filter: (page: { path: string }) =>
+    ![
+      '/this-route-does-not-exist',
+      '/redirect',
+      '/i-do-not-exist',
+      '/not-found/via-beforeLoad',
+      '/not-found/via-loader',
+      '/specialChars/search',
+      '/specialChars/hash',
+      '/specialChars/malformed',
+      '/users',
+    ].some((p) => page.path.includes(p)),
+  maxRedirects: 100,
+}
+
+export default defineConfig({
+  plugins: [
+    pluginReact(),
+    ...tanstackStart({
+      spa: isSpaMode ? spaModeConfiguration : undefined,
+      prerender: isPrerender ? prerenderConfiguration : undefined,
+    }),
+  ],
+  tools: {},
+  source: {
+    alias: {
+      '~': path.resolve(currentDir, 'src'),
+    },
+  },
+})

e2e/react-start/basic/scripts/run-bundler.mjs

@@ -0,0 +1,57 @@
+import { spawn } from 'node:child_process'
+
+const command = process.argv[2]
+const args = process.argv.slice(3)
+
+if (!command) {
+  console.error('Missing bundler command')
+  process.exit(1)
+}
+
+const bundler = process.env.BUNDLER === 'rsbuild' ? 'rsbuild' : 'vite'
+
+const extractPort = (args) => {
+  const portIndex = args.indexOf('--port')
+  if (portIndex >= 0 && args[portIndex + 1]) {
+    return args[portIndex + 1]
+  }
+  return null
+}
+
+const run = (cmd, cmdArgs) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(cmd, cmdArgs, {
+      stdio: 'inherit',
+      env: process.env,
+      shell: process.platform === 'win32',
+    })
+    child.on('error', (error) => {
+      reject(error)
+    })
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve()
+      } else {
+        reject(new Error(`${cmd} exited with code ${code}`))
+      }
+    })
+  })
+
+try {
+  if (bundler === 'rsbuild' && command === 'preview') {
+    const port = extractPort(args)
+    if (port) {
+      process.env.PORT = port
+    }
+    await run('node', ['server.js'])
+  } else {
+    await run(bundler, [command, ...args])
+
+    if (command === 'build') {
+      await run('tsc', ['--noEmit'])
+    }
+  }
+} catch (error) {
+  console.error(error)
+  process.exit(1)
+}

e2e/react-start/basic/server.js

@@ -18,7 +18,12 @@ export async function createStartServer() {
 
   // to keep testing uniform stop express from redirecting /posts to /posts/
   // when serving pre-rendered pages
-  app.use(express.static('./dist/client', { redirect: !isPrerender }))
+  app.use(
+    express.static('./dist/client', {
+      redirect: !isPrerender,
+      ...(isPrerender ? {} : { index: false }),
+    }),
+  )
 
   app.use(async (req, res, next) => {
     try {

e2e/react-start/basic/src/routeTree.gen.ts

@@ -1,9 +1,3 @@
-/* eslint-disable */
-
-// @ts-nocheck
-
-// noinspection JSUnusedGlobalSymbols
-
 // This file was automatically generated by TanStack Router.
 // You should NOT make any changes in this file as it will be overwritten.
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
@@ -1365,6 +1359,7 @@ export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)
   ._addFileTypes<FileRouteTypes>()
 
+
 import type { getRouter } from './router.tsx'
 import type { createStart } from '@tanstack/react-start'
 declare module '@tanstack/react-start' {

e2e/react-start/basic/src/routes/__root.tsx

@@ -10,7 +10,7 @@ import {
 
 import { DefaultCatchBoundary } from '~/components/DefaultCatchBoundary'
 import { NotFound } from '~/components/NotFound'
-import appCss from '~/styles/app.css?url'
+import '~/styles/app.css'
 import { seo } from '~/utils/seo'
 
 export const Route = createRootRoute({
@@ -30,7 +30,6 @@ export const Route = createRootRoute({
       }),
     ],
     links: [
-      { rel: 'stylesheet', href: appCss },
       {
         rel: 'apple-touch-icon',
         sizes: '180x180',

e2e/react-start/basic/src/styles/app.css

@@ -1,30 +1,57 @@
-@import 'tailwindcss' source('../');
-
-@layer base {
-  *,
-  ::after,
-  ::before,
-  ::backdrop,
-  ::file-selector-button {
-    border-color: var(--color-gray-200, currentcolor);
-  }
-}
-
-@layer base {
-  html {
-    color-scheme: light dark;
-  }
-
-  * {
-    @apply border-gray-200 dark:border-gray-800;
-  }
-
-  html,
-  body {
-    @apply text-gray-900 bg-gray-50 dark:bg-gray-950 dark:text-gray-200;
-  }
-
-  .using-mouse * {
-    outline: none !important;
-  }
+*,
+*::before,
+*::after,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+  border-color: #e5e7eb;
+}
+
+html {
+  color-scheme: light dark;
+}
+
+body {
+  margin: 0;
+  font-family:
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+  background-color: #f9fafb;
+  color: #111827;
+}
+
+.using-mouse * {
+  outline: none !important;
+}
+
+.p-2 {
+  padding: 0.5rem;
+}
+
+.py-2 {
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
+}
+
+.flex {
+  display: flex;
+}
+
+.gap-2 {
+  gap: 0.5rem;
+}
+
+.text-lg {
+  font-size: 1.125rem;
+}
+
+.font-bold {
+  font-weight: 700;
+}
+
+.italic {
+  font-style: italic;
 }

e2e/react-start/module-federation-rsbuild-host/README.md

@@ -0,0 +1,100 @@
+# E2E Fixture: TanStack Start Module Federation Host (Rsbuild)
+
+This fixture validates host behavior for Rsbuild + Module Federation in:
+
+- `ssr`
+- `spa`
+- `prerender`
+
+It consumes the paired remote fixture at:
+
+- `../module-federation-rsbuild-remote`
+
+## Commands
+
+```sh
+# SSR only
+pnpm test:e2e:ssr
+
+# SPA only
+pnpm test:e2e:spa
+
+# Prerender only
+pnpm test:e2e:prerender
+
+# Full mode matrix
+pnpm test:e2e
+```
+
+## Node SSR federation requirement
+
+Server remotes are loaded over HTTP from the remote SSR output and use:
+
+- `remoteType: 'script'` on the host SSR plugin config.
+- `shared.react/react-dom.import: false` on the remote node-target config.
+
+The e2e suite also validates the remote SSR manifest contract:
+
+- `metaData.remoteEntry.type === 'commonjs-module'`
+- `metaData.publicPath` points to `http://<remote-origin>/ssr/`
+- `metaData.types.zip === ''` and `metaData.types.api === ''`
+- React/ReactDOM shared entries use wildcard metadata (`version: '*'`, `requiredVersion: '^*'`) in SSR manifest.
+- React/ReactDOM shared fallback asset lists are empty in SSR manifest.
+- Exposed module JS assets remain relative `static/js/...` paths.
+- JS asset paths are expected to end with `.js`.
+
+It also validates the browser manifest contract for the remote web target:
+
+- `metaData.remoteEntry.type === 'global'`
+- `metaData.publicPath` points to `http://<remote-origin>/`
+- `metaData.types.zip === '@mf-types.zip'` and `metaData.types.api === '@mf-types.d.ts'`
+- React/ReactDOM shared entries use concrete non-wildcard versions in browser manifest.
+- React/ReactDOM shared fallback asset lists are populated in browser manifest.
+- Browser shared JS asset entries remain relative `static/js/...` paths (resolved via HTTP `publicPath`).
+- Exposed module JS assets remain relative `static/js/...` paths.
+
+Federation stats contract is also verified:
+
+- SSR stats shared entries set `import: false` for `react` and `react-dom`.
+- Browser stats shared entries omit `import` and keep standard web sharing metadata.
+- Manifest and stats metadata stay aligned (identity, remote entry type/publicPath, types metadata, shared/expose names).
+- Stats outputs keep exact expected cardinality (`shared: 2`, `exposes: 3`) and stable ids (`mf_remote:*`).
+- Alignment also covers build/plugin metadata (`buildInfo`, `pluginVersion`) and remoteEntry name/path fields.
+- Shared/expose JS asset lists are aligned between manifest and stats for both browser and SSR outputs.
+- Types metadata parity includes `types.path` and `types.name`, and shared/expose CSS asset lists are also aligned.
+- JSON endpoint checks also validate basic payload structure (`id`, `name`, `metaData.remoteEntry.name`, `pluginVersion`).
+- Endpoint payloads also keep identity metadata stable (`metaData.name: 'mf_remote'`, `metaData.type: 'app'`, and `buildInfo.buildVersion: 'local'`).
+- Endpoint payloads also preserve global metadata invariants (`metaData.globalName: 'mf_remote'`, `metaData.prefetchInterface: false`, `metaData.remoteEntry.path: ''`).
+- JSON endpoint checks assert path-specific metadata values:
+  - `/dist/*` endpoints return `remoteEntry.type: 'global'`, browser `types` metadata, and root publicPath.
+  - `/ssr/*` endpoints return `remoteEntry.type: 'commonjs-module'`, empty SSR `types` metadata, and `/ssr/` publicPath.
+- Endpoint `types.path` and `types.name` metadata are expected to stay empty strings (`''`) across both browser and SSR JSON payloads.
+- Endpoint payloads also keep consistent plugin/build metadata across all JSON endpoints (`pluginVersion`, `buildVersion`, `buildName`).
+- `pluginVersion` values are also expected to be SemVer-like strings on all JSON endpoints.
+- JSON endpoint payloads also enforce mode-correct shared version semantics (`react`/`react-dom` wildcard only on SSR endpoints).
+- Each JSON endpoint payload also keeps `remotes: []` and exactly two shared entries (`react`, `react-dom`).
+- Shared identity in each endpoint payload remains stable (`mf_remote:react`, `mf_remote:react-dom`).
+- Shared entries remain singleton on all endpoint payloads.
+- Stats endpoints retain shared runtime flags (`shareScope: 'default'`, `eager: false`, and SSR-only `import: false`), while manifest endpoints omit those fields.
+- Stats endpoints also keep shared usage arrays (`usedIn`, `usedExports`) as empty arrays, while manifest endpoints omit them.
+- Endpoint shared JS asset semantics remain mode-correct (`[]` for SSR shared entries, non-empty relative `static/js/*.js` for browser shared entries).
+- Shared endpoint payloads keep async JS asset arrays empty and CSS asset arrays empty.
+- Endpoint payloads also retain expose identity/path contracts for `message`, `routes`, and `server-data`.
+- Stats endpoint expose `requires` arrays remain empty; manifest endpoint payloads omit `requires`.
+- Stats endpoint payloads also retain stable expose `file` metadata (`src/message.tsx`, `src/routes.tsx`, `src/server-data.ts`).
+- Endpoint expose sync JS asset lists are non-empty and keep relative `static/js/*.js` paths.
+- Endpoint expose async JS and CSS asset arrays remain empty.
+
+Remote entry payloads are also validated directly over HTTP at:
+
+- `/dist/remoteEntry.js`
+- `/ssr/remoteEntry.js`
+
+and must return JavaScript content-types (not HTML fallback pages).
+
+The browser types artifact is also validated at:
+
+- `/dist/@mf-types.zip`
+
+and must be retrievable over HTTP as a non-HTML payload.
+