Implement react-server-dom-parcel (#31725)

This adds a new `react-server-dom-parcel-package`, which is an RSC
integration for the Parcel bundler. It is mostly copied from the
existing webpack/turbopack integrations, with some changes to utilize
Parcel runtime APIs for loading and executing bundles/modules.

See parcel-bundler/parcel#10043 for the Parcel
side of this, which includes the plugin needed to generate client and
server references. https://github.com/parcel-bundler/rsc-examples also
includes examples of various ways to use RSCs with Parcel.

Differences from other integrations:

* Client and server modules are all part of the same graph, and we use
Parcel's
[environments](https://parceljs.org/plugin-system/transformer/#the-environment)
to distinguish them. The server is the Parcel build entry point, and it
imports and renders server components in route handlers. When a `"use
client"` directive is seen, the environment changes and Parcel creates a
new client bundle for the page, combining all client modules together.
CSS from both client and server components are also combined
automatically.
* There is no separate manifest file that needs to be passed around by
the user. A [Runtime](https://parceljs.org/plugin-system/runtime/)
plugin injects client and server references as needed into the relevant
bundles, and registers server action ids using `react-server-dom-parcel`
automatically.
* A special `<Resources>` component is also generated by Parcel to
render the `<script>` and `<link rel="stylesheet">` elements needed for
a page, using the relevant info from the bundle graph.

Note: I've already published a 0.0.x version of this package to npm for
testing purposes but happy to add whoever needs access to it as well.

### Questions

* How to test this in the React repo. I'll have integration tests in
Parcel, but setting up all the different mocks and environments to
simulate that here seems challenging. I could try to copy how
Webpack/Turbopack do it but it's a bit different.
* Where to put TypeScript types. Right now I have some ambient types in
my [example
repo](https://github.com/parcel-bundler/rsc-examples/blob/main/types.d.ts)
but it would be nice for users not to copy and paste these. Can I
include them in the package or do they need to maintained separately in
definitelytyped? I would really prefer not to have to maintain code in
three different repos ideally.

---------

Co-authored-by: Sebastian Markbage <[email protected]>

Author: devongovett

.eslintrc.js

@@ -330,6 +330,7 @@ module.exports = {
         'packages/react-server-dom-esm/**/*.js',
         'packages/react-server-dom-webpack/**/*.js',
         'packages/react-server-dom-turbopack/**/*.js',
+        'packages/react-server-dom-parcel/**/*.js',
         'packages/react-server-dom-fb/**/*.js',
         'packages/react-test-renderer/**/*.js',
         'packages/react-debug-tools/**/*.js',
@@ -481,6 +482,12 @@ module.exports = {
         __turbopack_require__: 'readonly',
       },
     },
+    {
+      files: ['packages/react-server-dom-parcel/**/*.js'],
+      globals: {
+        parcelRequire: 'readonly',
+      },
+    },
     {
       files: ['packages/scheduler/**/*.js'],
       globals: {

ReactVersions.js

@@ -40,6 +40,7 @@ const stablePackages = {
   'react-dom': ReactVersion,
   'react-server-dom-webpack': ReactVersion,
   'react-server-dom-turbopack': ReactVersion,
+  'react-server-dom-parcel': ReactVersion,
   'react-is': ReactVersion,
   'react-reconciler': '0.31.0',
   'react-refresh': '0.16.0',

fixtures/flight-parcel/.gitignore

@@ -0,0 +1,5 @@
+.parcel-cache
+.DS_Store
+node_modules
+dist
+todos.json

fixtures/flight-parcel/.parcelrc

@@ -0,0 +1,4 @@
+{
+  "extends": "@parcel/config-default",
+  "runtimes": ["...", "@parcel/runtime-rsc"]
+}

fixtures/flight-parcel/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "flight-parcel",
+  "private": true,
+  "workspaces": [
+    "examples/*"
+  ],
+  "server": "dist/server.js",
+  "targets": {
+    "server": {
+      "source": "src/server.tsx",
+      "context": "react-server",
+      "outputFormat": "commonjs",
+      "includeNodeModules": {
+        "express": false
+      }
+    }
+  },
+  "scripts": {
+    "predev": "cp -r ../../build/oss-experimental/* ./node_modules/",
+    "prebuild": "cp -r ../../build/oss-experimental/* ./node_modules/",
+    "dev": "concurrently \"npm run dev:watch\" \"npm run dev:start\"",
+    "dev:watch": "NODE_ENV=development parcel watch",
+    "dev:start": "NODE_ENV=development node dist/server.js",
+    "build": "parcel build",
+    "start": "node dist/server.js"
+  },
+  "@parcel/resolver-default": {
+    "packageExports": true
+  },
+  "dependencies": {
+    "@parcel/config-default": "2.0.0-dev.1789",
+    "@parcel/runtime-rsc": "2.13.3-dev.3412",
+    "@types/parcel-env": "^0.0.6",
+    "@types/express": "*",
+    "@types/node": "^22.10.1",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "concurrently": "^7.3.0",
+    "express": "^4.18.2",
+    "parcel": "2.0.0-dev.1787",
+    "process": "^0.11.10",
+    "react": "experimental",
+    "react-dom": "experimental",
+    "react-server-dom-parcel": "experimental",
+    "rsc-html-stream": "^0.0.4",
+    "ws": "^8.8.1"
+  },
+  "@parcel/bundler-default": {
+    "minBundleSize": 0
+  }
+}

fixtures/flight-parcel/src/Dialog.tsx

@@ -0,0 +1,21 @@
+'use client';
+
+import {ReactNode, useRef} from 'react';
+
+export function Dialog({
+  trigger,
+  children,
+}: {
+  trigger: ReactNode;
+  children: ReactNode;
+}) {
+  let ref = useRef<HTMLDialogElement | null>(null);
+  return (
+    <>
+      <button onClick={() => ref.current?.showModal()}>{trigger}</button>
+      <dialog ref={ref} onSubmit={() => ref.current?.close()}>
+        {children}
+      </dialog>
+    </>
+  );
+}

fixtures/flight-parcel/src/TodoCreate.tsx

@@ -0,0 +1,18 @@
+import {createTodo} from './actions';
+
+export function TodoCreate() {
+  return (
+    <form action={createTodo}>
+      <label>
+        Title: <input name="title" />
+      </label>
+      <label>
+        Description: <textarea name="description" />
+      </label>
+      <label>
+        Due date: <input type="date" name="dueDate" />
+      </label>
+      <button>Add todo</button>
+    </form>
+  );
+}

fixtures/flight-parcel/src/TodoDetail.tsx

@@ -0,0 +1,25 @@
+import {getTodo, updateTodo} from './actions';
+
+export async function TodoDetail({id}: {id: number}) {
+  let todo = await getTodo(id);
+  if (!todo) {
+    return <p>Todo not found</p>;
+  }
+
+  return (
+    <form className="todo" action={updateTodo.bind(null, todo.id)}>
+      <label>
+        Title: <input name="title" defaultValue={todo.title} />
+      </label>
+      <label>
+        Description:{' '}
+        <textarea name="description" defaultValue={todo.description} />
+      </label>
+      <label>
+        Due date:{' '}
+        <input type="date" name="dueDate" defaultValue={todo.dueDate} />
+      </label>
+      <button type="submit">Update todo</button>
+    </form>
+  );
+}

fixtures/flight-parcel/src/TodoItem.tsx

@@ -0,0 +1,37 @@
+'use client';
+
+import {startTransition, useOptimistic} from 'react';
+import {deleteTodo, setTodoComplete, type Todo as ITodo} from './actions';
+
+export function TodoItem({
+  todo,
+  isSelected,
+}: {
+  todo: ITodo;
+  isSelected: boolean;
+}) {
+  let [isOptimisticComplete, setOptimisticComplete] = useOptimistic(
+    todo.isComplete,
+  );
+
+  return (
+    <li data-selected={isSelected || undefined}>
+      <input
+        type="checkbox"
+        checked={isOptimisticComplete}
+        onChange={e => {
+          startTransition(async () => {
+            setOptimisticComplete(e.target.checked);
+            await setTodoComplete(todo.id, e.target.checked);
+          });
+        }}
+      />
+      <a
+        href={`/todos/${todo.id}`}
+        aria-current={isSelected ? 'page' : undefined}>
+        {todo.title}
+      </a>
+      <button onClick={() => deleteTodo(todo.id)}>x</button>
+    </li>
+  );
+}

fixtures/flight-parcel/src/TodoList.tsx

@@ -0,0 +1,13 @@
+import {TodoItem} from './TodoItem';
+import {getTodos} from './actions';
+
+export async function TodoList({id}: {id: number | undefined}) {
+  let todos = await getTodos();
+  return (
+    <ul className="todo-list">
+      {todos.map(todo => (
+        <TodoItem key={todo.id} todo={todo} isSelected={todo.id === id} />
+      ))}
+    </ul>
+  );
+}