React Server Components (RSC) Pipeline

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• README.md
• packages/farmjs-plugin/src/rsc/index.ts
• packages/farmjs-plugin/src/rsc/entries/rsc.ts
• packages/farm/src/nitro/universal-build.ts
• packages/farmjs-plugin/src/rsc/compatibility.test.ts

The React Server Components (RSC) Pipeline provides a purpose-built architecture for rendering, streaming, and hydrating React components. It integrates Vite for development with a multi-environment build system that generates specific outputs for the RSC runtime, Server-Side Rendering (SSR), and the client.

Sources: README.md:21, packages/farmjs-plugin/src/rsc/index.ts:1-12

Pipeline Architecture

The pipeline manages three distinct build environments to handle the lifecycle of an RSC request. In development, the Vite dev server intercepts requests and coordinates between these environments. In production, the build process generates optimized bundles for each.

The diagram shows how requests flow through the Server Components environment to produce either a direct RSC payload for client navigation or an HTML response via the SSR environment for initial loads.

Sources: ARCHITECTURE.md:65-75, packages/farmjs-plugin/src/rsc/index.ts:14-25

Build Environments

The pipeline configures three specific environments during the build process:

Environment	Purpose	Conditions
rsc	Renders React components to a wire format payload.	react-server, node, import
ssr	Consumes the RSC stream to generate initial HTML.	node, import
client	Handles browser hydration and subsequent navigations.	browser, import

Sources: packages/farmjs-plugin/src/rsc/index.ts:517-536

Development Request Flow

The farmRsc plugin handles page rendering during development by injecting middleware into the Vite server.

1. Intercept Request: The dev server middleware identifies non-asset requests.
2. Load RSC Entry: The server loads the virtual RSC entry point (virtual:@farm.js/rsc/entry-rsc) within the rsc environment.
3. Execute Fetch: The pipeline calls the fetch handler of the RSC entry with the incoming request.
4. Negotiate Response:
   • If the Accept header includes text/x-component, the server returns the raw RSC stream.
   • Otherwise, the RSC environment delegates to the ssr environment to produce a full HTML document.

Sources: packages/farmjs-plugin/src/rsc/index.ts:795-888, packages/farmjs-plugin/src/rsc/entries/rsc.ts:401-419

Server Actions and Mutations

Server Actions allow Client Components to call server-side functions directly. The pipeline secures these actions through a specific validation and execution flow.

The sequence diagram illustrates the secure execution of a Server Action from the client through the pipeline.

Sources: packages/farmjs-plugin/src/rsc/entries/rsc.ts:250-316, packages/farmjs-plugin/src/rsc/index.ts:832-841

Action Handling Logic

The pipeline processes Server Actions in two modes:

• JavaScript Mode: Used after hydration. The client sends a POST request with an x-farm-action-id header. The pipeline uses decodeReply to parse arguments and loadServerAction to find the target function.
• Progressive Enhancement: Used before JavaScript loads. The pipeline uses decodeAction to process standard FormData submissions, ensuring forms work without client-side JS.

Sources: packages/farmjs-plugin/src/rsc/entries/rsc.ts:271-314

Production Build and Nitro Integration

The production pipeline uses a universal build process that targets Nitro-powered environments like Vercel or Cloudflare.

SSR Entry Generation

The pipeline generates a virtual SSR entry that bundles all API routes, page routes, and layout modules. This entry includes the fetch handler that Nitro consumes.

// Example of generated production entry structure
export async function fetch(request, context) {
  return _runWithAPIRequestRuntime({
    basePath: farmLocalAPIBasePath,
    dispatch: async (localRequest) => 
      (await handleAPIRequest(localRequest)) ?? Response.json({ error: "Not Found" }, { status: 404 }),
  }, () => handleFarmFetch(request, context));
}

Sources: packages/farm/src/nitro/universal-build.ts:1625-1631, packages/farm/src/nitro/universal-build.ts:2104-2115

Prerendering and SSG

During the build, the pipeline identifies Static Site Generation (SSG) candidates. If a route does not depend on request-specific state (like cookies or auth), the pipeline prerenders it into physical HTML files.

Sources: packages/farm/src/nitro/universal-build.ts:1817-1854

Configuration Options

RSC behavior is controlled via the experimental block in farm.config.ts.

Option	Type	Default	Description
serverComponents	boolean	true	Enables React Server Components rendering.
serverActions	boolean	false	Enables "use server" actions and public POST decoding.
optimizedBoundary	boolean	false	Uses the native Strata renderer for server-only host subtrees.

Sources: packages/farmjs-plugin/src/rsc/index.ts:93-113

The React Server Components pipeline ensures a unified flow for data fetching and UI rendering by maintaining strict boundaries between server logic and client interactivity. This architecture enables features like zero-bundle-size components and direct backend access while preserving a fast development cycle through Vite integration.