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

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.

apps/rsc-demo/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at <[email protected]>. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

apps/rsc-demo/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:lts-hydrogen
+
+WORKDIR /opt/notes-app
+
+COPY package.json package-lock.json ./
+
+RUN npm install --legacy-peer-deps
+
+COPY . .
+
+ENTRYPOINT [ "npm", "run" ]
+CMD [ "start" ]

apps/rsc-demo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.