feat(rsc-demo): React Server Components demo with Module Federation

.github/workflows/build-and-test.yml

@@ -138,6 +138,11 @@ jobs:
     uses: ./.github/workflows/e2e-router.yml
     secrets: inherit
 
+  e2e-rsc:
+    needs: checkout-install
+    uses: ./.github/workflows/e2e-rsc.yml
+    secrets: inherit
+
   e2e-metro:
     permissions:
       contents: read

.github/workflows/e2e-rsc.yml

@@ -0,0 +1,77 @@
+# .github/workflows/e2e-rsc.yml
+name: E2E RSC Demo
+
+on:
+  workflow_call:
+
+jobs:
+  e2e-rsc:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Cache Tool Downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache
+          key: ${{ runner.os }}-toolcache-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-toolcache-
+
+      - name: Install Pnpm
+        run: |
+          corepack prepare pnpm@8.11.0 --activate
+          corepack enable
+
+      - name: Setup Node.js 18
+        uses: actions/setup-node@v5
+        with:
+          node-version: '18'
+          cache: 'pnpm'
+
+      - name: Set Nx SHA
+        uses: nrwl/nx-set-shas@v3
+
+      - name: Set SKIP_DEVTOOLS_POSTINSTALL environment variable
+        run: echo "SKIP_DEVTOOLS_POSTINSTALL=true" >> "$GITHUB_ENV"
+
+      - name: Install Dependencies
+        run: pnpm install
+
+      - name: Run Build for All Packages
+        run: npx nx run-many --targets=build --projects=tag:type:pkg
+
+      - name: Build RSC Demo App1
+        working-directory: apps/rsc-demo/packages/app1
+        run: pnpm build
+
+      - name: Build RSC Demo App2
+        working-directory: apps/rsc-demo/packages/app2
+        run: pnpm build
+
+      - name: Verify SSR Registry Injection
+        run: |
+          echo "Checking app1 SSR registry injection..."
+          head -c 100 apps/rsc-demo/packages/app1/build/ssr.js | grep -q "__RSC_SSR_REGISTRY_INJECTED__" || (echo "ERROR: SSR registry not injected in app1" && exit 1)
+          echo "Checking app2 SSR registry injection..."
+          head -c 100 apps/rsc-demo/packages/app2/build/ssr.js | grep -q "__RSC_SSR_REGISTRY_INJECTED__" || (echo "ERROR: SSR registry not injected in app2" && exit 1)
+          echo "SSR registry injection verified in both apps"
+
+      - name: Verify Manifest Files
+        run: |
+          echo "Checking manifest files..."
+          test -f apps/rsc-demo/packages/app1/build/react-client-manifest.json || (echo "ERROR: react-client-manifest.json missing in app1" && exit 1)
+          test -f apps/rsc-demo/packages/app1/build/react-ssr-manifest.json || (echo "ERROR: react-ssr-manifest.json missing in app1" && exit 1)
+          test -f apps/rsc-demo/packages/app1/build/react-server-actions-manifest.json || (echo "ERROR: react-server-actions-manifest.json missing in app1" && exit 1)
+          test -f apps/rsc-demo/packages/app2/build/react-client-manifest.json || (echo "ERROR: react-client-manifest.json missing in app2" && exit 1)
+          test -f apps/rsc-demo/packages/app2/build/react-ssr-manifest.json || (echo "ERROR: react-ssr-manifest.json missing in app2" && exit 1)
+          test -f apps/rsc-demo/packages/app2/build/react-server-actions-manifest.json || (echo "ERROR: react-server-actions-manifest.json missing in app2" && exit 1)
+          echo "All manifest files present"
+
+      - name: Run RSC E2E Tests
+        working-directory: apps/rsc-demo/packages/e2e
+        run: pnpm test:rsc

Option2Plan.md

@@ -0,0 +1,58 @@
+# Option 2 (MF-Native RSC Actions) – Execution Plan
+
+Goal: execute remote “use server” modules in-process via Module Federation, without HTTP forwarding, while keeping HTTP as a safe fallback. This must work for RSC, SSR, client hydration, shared packages, and layered share scopes.
+
+## Outcomes
+- Host can `getServerAction(id)` for remote actions loaded via MF.
+- No filesystem coupling; remotes discovered over HTTP via MF manifest data.
+- Layer-aware sharing preserved (rsc vs client).
+- Tests cover MF-native path plus fallback to HTTP.
+- Works when remotes are deployed separately (no shared filesystem) and when the remote HTTP server is offline (MF container already loaded).
+
+## Workstream A – Remote publishes the right metadata
+1) **MF manifest extraData**: ensure remote (e.g., app2) publishes in `manifest.additionalData`:
+   - `rsc.serverActionsManifest`, `rsc.clientManifest`, `rsc.remote.url`, `rsc.remote.serverContainer`, `rsc.remote.actionsEndpoint`.
+   - `rsc.exposeTypes` marking `./server-actions` as `server-action` (and other exposes as `client-component`, `server-component`, etc.).
+   - (Optional) `rsc.layers` map so the host knows which shareScope each expose expects.
+2) **Public paths**: remoteEntry.server.js, mf-stats.json, manifests all served over HTTP (no fs paths).
+3) **Share scopes**: keep `shareScope: 'rsc'` for server layer, `'client'` for browser; include `react`, `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-server-dom-webpack/server`.
+
+## Workstream B – Host runtime plugin wiring
+1) **Runtime plugin** (rscRuntimePlugin):
+   - On remote load, read MF manifest extraData (or mf-stats fallback).
+   - Fetch `serverActionsManifest` URL; cache by URL.
+   - For `server-actions` exposes, call `registerServerReference(fn, id, exportName)` for every manifest entry belonging to that remote.
+   - Use `resolveShare` / `loadShare` hooks to map to the correct shareScope based on issuer layer (rsc vs client), avoiding alias hacks.
+   - Emit structured logs (DEBUG) for: manifest fetch, module load, registration counts, and failures; surface a non-fatal warning when MF load fails so HTTP fallback remains available.
+2) **Host RSC entry**: ensure host imports remote `server-actions` so MF loads the container in the RSC layer (or trigger via lazy load during first request).
+3) **Option ordering** in `/react` handler:
+   - Try `getServerAction(id)` (populated by runtime plugin).
+   - If missing and remote match → HTTP forward (Option 1) as fallback.
+   - Add a small counter/metric for MF hits vs HTTP fallbacks.
+
+## Workstream C – Loader & plugin alignment
+1) **rsc-server-loader**: when processing MF-imported modules, preserve the canonical module URL from the manifest (do not rewrite to host paths) when calling `registerServerReference`.
+2) **react-server-dom-webpack plugin**: ensure manifest generation includes MF-imported actions (buildInfo flags already set; just respect provided module URLs).
+3) **No build-time manifest merge** in the host; everything discovered at runtime via MF data.
+4) **Client manifest for SSR (optional stretch)**: allow runtime plugin to fetch `clientManifest` from remote and merge into SSR worker’s manifest if we later SSR remote client islands.
+
+## Workstream D – Tests
+1) Unit: assert runtime plugin fetches extraData URLs, registers actions, and populates `getServerAction` without HTTP.
+2) Integration (node --test): start host only, stop remote HTTP server, verify remote actions still execute (pure MF). Then start remote server to confirm HTTP fallback still works when MF load fails.
+3) E2E: browser flows unchanged; add a case where host uses MF-native action and HTTP server is down.
+4) Negative tests: malformed extraData URL, missing manifest, incompatible shareScope, and mismatched React version in remote (should log and fall back).
+5) Performance check: compare latency of MF-native vs HTTP forward; assert no extra network calls for manifest after first fetch (cache hit).
+
+## Rollout Steps
+1) Update remote MF config to emit extraData URLs over HTTP.
+2) Update rscRuntimePlugin to prefer extraData, cache by manifest URL, and use loadShare for layer-aware React sharing.
+3) Ensure host server-entry imports remote server-actions (or lazy load before first action).
+4) Remove any residual build-time merges; rely solely on runtime discovery.
+5) Add tests (unit + integration + e2e) for MF-native path and fallback behavior.
+6) Add observability: lightweight counters for MF registrations, MF load failures, HTTP fallbacks; optionally expose in logs or a diagnostics endpoint.
+
+## Open Questions
+- MF runtime “factory is not a function” on Node: diagnose container format vs runtime plugin; may need `@module-federation/node` runtimePlugin ordering or `library.type: 'commonjs-module'` alignment.
+- Should remote also publish RSC client manifest URL for host-side SSR of remote client components? If yes, extend runtime plugin to fetch/merge client manifests for SSR worker.
+- Do we need per-remote auth headers/cookies when fetching manifests over HTTP? If so, allow a configurable fetch hook in the runtime plugin.
+- How to handle version skew of `react-server-dom-webpack` between host and remote? Consider validating major/minor in extraData and warning/falling back to HTTP.

apps/rsc-demo/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+**/node_modules/
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+/dist
+**/dist
+/packages/app1/dist
+/packages/app2/dist
+**/build
+/packages/app1/build
+/packages/app2/build
+
+# notes
+notes/*.md
+!notes/RESEARCH.md
+test-results/
+
+# misc
+.DS_Store
+.eslintcache
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# vscode
+.vscode

apps/rsc-demo/.nvmrc

@@ -0,0 +1 @@
+18.19.1

apps/rsc-demo/.prettierignore

@@ -0,0 +1,27 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+/dist
+
+# misc
+.DS_Store
+.eslintcache
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+*.html
+*.json
+*.md

apps/rsc-demo/.prettierrc.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+'use strict';
+
+module.exports = {
+  arrowParens: 'always',
+  bracketSpacing: false,
+  singleQuote: true,
+  jsxBracketSameLine: true,
+  trailingComma: 'es5',
+  printWidth: 80,
+};

apps/rsc-demo/AGENTS.md

@@ -0,0 +1,43 @@
+# Repository Guidelines
+
+## Project Structure & Modules
+- Monorepo managed by `pnpm`. Primary apps live in `packages/app1` and `packages/app2`; shared RSC tooling is in `packages/react-server-dom-webpack`.
+- App source: `packages/*/src`. Servers: `packages/*/server`. Webpack configs and build scripts: `packages/*/scripts`.
+- Tests: unit/integration in `packages/e2e/rsc`, Playwright E2E in `packages/e2e/e2e`. Build output lands in `packages/*/build` (gitignored).
+
+## Build, Test, Dev Commands
+- `pnpm install` — install workspace deps.
+- `pnpm start` — run app1 dev server with webpack watch (bundler + server).
+- `pnpm --filter app2 start` — same for app2.
+- `pnpm run build` — production builds for app1 and app2 (client + server layers).
+- `pnpm test` — top-level test entry; runs RSC tests and MF tests after building.
+- `pnpm run test:rsc` — RSC unit/integration tests (Node `--test`).
+- `pnpm run test:e2e:rsc` — Playwright smoke for the RSC notes apps.
+- `pnpm run test:e2e` — all Playwright suites (requires prior build).
+
+## Coding Style & Naming
+- JavaScript/React with ES modules; prefer functional components.
+- Indent with 2 spaces; keep files ASCII-only unless existing file uses Unicode.
+- Client components carry the `'use client'` directive; server actions/components avoid it. Name server action files `*.server.js` when possible.
+- Webpack chunk/module ids are kept readable (`chunkIds: 'named', moduleIds: 'named'`).
+
+## Testing Guidelines
+- Frameworks: Node’s built-in `node --test`, Playwright for E2E.
+- Place unit/integration specs under `packages/e2e/rsc`. Name with `.test.js`.
+- E2E specs live in `packages/e2e/e2e`; keep them idempotent and avoid relying on pre-existing data.
+- Run `pnpm run build` before E2E to ensure assets exist.
+
+## Commit & PR Expectations
+- Use concise, descriptive commit messages (e.g., `fix: inline action manifest ids`).
+- For PRs, include: summary of changes, testing performed (`pnpm test:rsc`, `pnpm test:e2e:rsc`), and any follow-up risks or TODOs.
+
+## Module Federation Configuration
+- ALL Module Federation plugins MUST include `experiments: { asyncStartup: true }` in their configuration (both client and server).
+- ALL shared modules MUST use `eager: false` - no exceptions. The federation runtime handles async loading.
+- Server-side code using asyncStartup bundles must `await` the module loads since module init is async.
+- Use separate share scopes for different layers: `'client'` for browser bundles, `'rsc'` for RSC server bundles.
+- Shared modules must also specify `layer` and `issuerLayer` matching the webpack layer they belong to (e.g., `client`, `rsc`, `ssr`).
+
+## Security & Config Tips
+- Do not check `packages/*/build` or credentials into git; `.gitignore` already covers build artifacts.
+- If enabling Postgres locally, gate with `USE_POSTGRES` and ensure fallback to the mock DB for offline runs.