facebook/react

react-server

Active contributors: sebmarkbage, gnoff, eps1lon, acdlite, unstubbable

Purpose

packages/react-server/ is a server-side runtime that powers two of React's most ambitious systems:

Fizz — the streaming HTML server-side renderer used by react-dom/server.*, react-dom/static.*, and (transitively) every framework that does SSR with React 18+.
Flight — the React Server Components writer. It produces the streamed Flight payload that react-server-dom-* packages parse on the client.

Both engines share a lot of infrastructure: the streaming primitives, the thenable handling, the call-user-space wrappers, and a custom Hooks dispatcher. They are intentionally co-located so they can cross-pollinate.

react-server is not intended to be imported directly by app code. It is a private dependency of react-dom, react-server-dom-webpack, react-server-dom-parcel, etc.

Directory layout

packages/react-server/src/
├── ReactFizzServer.js                   # ~6,500 lines: the streaming HTML engine
├── ReactFizzClassComponent.js           # class-component support inside Fizz
├── ReactFizzHooks.js                    # the SSR hooks dispatcher
├── ReactFizzThenable.js                 # use(promise) inside SSR
├── ReactFizzNewContext.js / ReactFizzLegacyContext.js
├── ReactFizzTreeContext.js
├── ReactFizzComponentStack.js
├── ReactFizzCallUserSpace.js
├── ReactFizzAsyncDispatcher.js
├── ReactFizzCurrentTask.js
├── ReactFizzViewTransitionComponent.js
├── ReactFizzConfig.js                   # the Fizz host-config interface (resolved per platform)
│
├── ReactFlightServer.js                 # ~6,800 lines: the Flight (RSC) writer
├── ReactFlightActionServer.js           # Server Actions on the server side
├── ReactFlightAsyncSequence.js
├── ReactFlightCallUserSpace.js
├── ReactFlightHooks.js                  # the RSC hooks dispatcher
├── ReactFlightReplyServer.js            # decoding form bodies / replies
├── ReactFlightServerConfig*.js          # bundler-pluggable config
├── ReactFlightServerTemporaryReferences.js
├── ReactFlightStackConfigV8.js
├── ReactFlightThenable.js
│
├── ReactServerStreamConfig.js           # stream interface (resolved per platform)
├── ReactServerStreamConfig{Browser,Node,Edge,Bun,FB}.js
├── ReactServerConsoleConfig{Browser,Plain,Server}.js
├── ReactSharedInternalsServer.js        # the server-side shared internals
├── createFastHashJS.js                  # tiny non-cryptographic hash for resource keys
├── flight/                              # Flight-specific subutilities
└── forks/                               # per-build entry resolution

Key abstractions

Fizz

Abstraction	File	Description
`createRequest` / `startWork` / `performWork`	`packages/react-server/src/ReactFizzServer.js`	The Fizz request lifecycle: queue work, render in chunks, write to stream.
`Task`	`packages/react-server/src/ReactFizzServer.js`	Unit of streaming work. Each Suspense boundary becomes one or more tasks.
`Segment`	same	A region of HTML that may suspend. Segments map to the JS-emitted "boundary completed / errored" pieces in the stream.
`BoundaryInstance`	same	The runtime representation of a Suspense boundary on the server side.
Hooks dispatcher	`packages/react-server/src/ReactFizzHooks.js`	A subset of hooks that work in SSR (`useState` returns the initial; `useEffect` is a no-op; etc.).
Stream config	`packages/react-server/src/ReactServerStreamConfigNode.js` (Edge, Browser, Bun, FB)	`pushChunk`, `flushBuffered`, `close`, `writeChunk`, etc. — abstracted per platform.
Host config	`packages/react-server/src/ReactFizzConfig.js`, resolved at build time to e.g. `react-dom-bindings/src/server/ReactFizzConfigDOM.js`	What host elements look like in HTML.
Inline runtime	`scripts/rollup/generate-inline-fizz-runtime.js`	The tiny JS snippet inlined into HTML for boundary completion / hydration.

Flight (RSC)

Abstraction	File	Description
`createRequest` / `startRender`	`packages/react-server/src/ReactFlightServer.js`	The Flight writer entry — mirrors Fizz's structure but emits the wire format.
Wire format rows	same	Each row is `<id>:<tag><payload>\n`. Tags include `J` (model), `I` (import / module), `H` (hint), `D` (debug), `E` (error), `T` (text), `K` (postpone), and many more. The full list is documented inline at the top of `ReactFlightServer.js`.
Server reference	`packages/react-server/src/ReactFlightActionServer.js`	A function the client can call back into; encoded in the stream as a "module" reference.
Temporary reference	`packages/react-server/src/ReactFlightServerTemporaryReferences.js`	Used to round-trip values that don't have a stable id (e.g. opaque thenables).
Reply server	`packages/react-server/src/ReactFlightReplyServer.js`	Decodes form-data / multipart bodies sent back from the client. The "request body" half of Server Actions.
Hooks dispatcher	`packages/react-server/src/ReactFlightHooks.js`	A heavily reduced hooks surface; on the RSC server, hooks like `useState` are not allowed.
Bundler config	`packages/react-server/src/ReactFlightServerConfig.js` (resolved per bundler)	Determines how a "client reference" is encoded — webpack, parcel, turbopack, esm, etc.

How it works

Fizz

sequenceDiagram
  participant App as User
  participant Fizz as ReactFizzServer
  participant Stream as Output stream
  participant Browser as Browser

  App->>Fizz: renderToReadableStream(&lt;App/&gt;, opts)
  loop while work to do
    Fizz->>Fizz: render a segment
    alt no suspense thrown
      Fizz->>Stream: emit HTML
    else thenable thrown
      Fizz->>Fizz: register fallback HTML
      Fizz->>Stream: emit fallback inline
      Fizz-->>Fizz: when thenable resolves, emit completed boundary script
      Fizz->>Stream: emit JS to swap fallback for content
    end
  end
  Fizz->>Stream: close
  Stream->>Browser: ...

Suspense boundaries are rendered with their fallbacks first; when a boundary's content is ready, a small inline script (packages/react-server/src/forks/Inline*.js) swaps the fallback for the real content. The same machinery powers prerender and resume: instead of waiting for boundaries forever, a postpone() call emits a "postponed" marker and stops; later, a different request can pick up where the prerender left off.

Flight

The Flight writer takes a server-only React tree and produces the wire format. Each tree node becomes a row in the stream. Client references (components marked "use client") are encoded as module pointers — the bundler's manifest is what turns "this id" into "this URL of this JS chunk". Server references (functions marked "use server") are encoded as callable handles that, when invoked from the client, hit a server endpoint; the body of the response goes back through ReactFlightReplyServer.

The wire format is intentionally append-only and self-describing — a client can start consuming rows as soon as it gets bytes, without waiting for the whole tree.

Integration points

react-dom uses Fizz. packages/react-dom/src/server/ReactDOMFizzServerNode.js (and Edge / Browser / Bun) imports ReactFizzServer.js from here.
react-server-dom-* packages use Flight. They import ReactFlightServer.js from here and provide a bundler-specific ReactFlightServerConfig*.js.
react — server runtimes install ReactSharedInternalsServer rather than the client one. The dispatcher swap happens in ReactFizzHooks.js / ReactFlightHooks.js.

Entry points for modification

Adding a new wire-format row in Flight: edit the encoder in packages/react-server/src/ReactFlightServer.js and the matching decoder in every react-server-dom-* client. The format is a contract.
Adding a new SSR-supported hook: implement it in packages/react-server/src/ReactFizzHooks.js and add a row for it in the dispatcher table. Make sure it's a no-op or sane-default behavior — there is no client to send updates to.
Adding a new platform stream driver: create a ReactServerStreamConfig<Platform>.js and wire it up in the matching react-dom/src/server/ReactDOMFizzServer<Platform>.js.
Changing how Server Actions encode body parts: ReactFlightReplyServer.js is one of the largest files in the package and the contract has compatibility implications. Read the existing tag table (packages/react-server-dom-webpack/src/ReactFlightReplyClient.js) before editing.

packages/react-server-dom — the bundler-specific Flight clients.
features/server-components — end-to-end RSC pipeline.
packages/react-dom — the package that exposes Fizz to users.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.