@tanstack/react-start-rsc 0.0.0

package/src/plugin/vite.ts

@@ -0,0 +1,241 @@
+import { fileURLToPath } from 'node:url'
+import path from 'pathe'
+import { resolveViteId } from '@tanstack/start-plugin-core/utils'
+import type {
+  TanStackStartVitePluginCoreOptions,
+  ViteRscForwardSsrResolverStrategy,
+} from '@tanstack/start-plugin-core/vite/types'
+import type { Plugin, PluginOption, UserConfig } from 'vite'
+
+type VirtualModuleLoadHandler = (this: {
+  environment: { name: string }
+}) => string
+const isClientEnvironment = (env: { config: { consumer: string } }) =>
+  env.config.consumer === 'client'
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function createVirtualModule(opts: {
+  name: string
+  moduleId: string
+  load: VirtualModuleLoadHandler
+  apply?: Plugin['apply']
+  applyToEnvironment?: Plugin['applyToEnvironment']
+}): Plugin {
+  const resolvedId = resolveViteId(opts.moduleId)
+  const idFilter = { id: new RegExp(escapeRegExp(opts.moduleId)) }
+
+  return {
+    name: opts.name,
+    apply: opts.apply,
+    applyToEnvironment: opts.applyToEnvironment,
+    resolveId: {
+      filter: idFilter,
+      handler() {
+        return resolvedId
+      },
+    },
+    load: {
+      filter: idFilter,
+      handler: opts.load,
+    },
+  }
+}
+
+// Virtual module ids used by the React Start RSC runtime.
+const RSC_HMR_VIRTUAL_ID = 'virtual:tanstack-rsc-hmr'
+const RSC_RUNTIME_VIRTUAL_ID = 'virtual:tanstack-rsc-runtime'
+const RSC_BROWSER_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-browser-decode'
+const RSC_SSR_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-ssr-decode'
+const RSC_ENV_NAME = 'rsc'
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url))
+const entryDir = path.resolve(currentDir, '..', '..', 'plugin', 'entry')
+const rscEntryPath = path.resolve(entryDir, 'rsc.tsx')
+
+export function configureRsc(): {
+  envName: string
+  providerEnvironmentName: TanStackStartVitePluginCoreOptions['providerEnvironmentName']
+  ssrResolverStrategy: TanStackStartVitePluginCoreOptions['ssrResolverStrategy']
+  serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters']
+} {
+  const serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters'] =
+    [
+      // IMPORTANT: plugin-adapters-plugin only calls the top-level factory once.
+      // That factory must return a flat array of adapters (not nested arrays),
+      // otherwise router-core ends up with non-adapter entries and Seroval crashes.
+      {
+        client: {
+          module: '@tanstack/react-start/rsc/serialization/client',
+          export: 'rscSerializationAdapter',
+          isFactory: true,
+        },
+        server: {
+          module: '@tanstack/react-start/rsc/serialization/server',
+          export: 'rscSerializationAdapter',
+          isFactory: true,
+        },
+      },
+    ]
+  const ssrResolverStrategy = {
+    type: 'vite-rsc-forward',
+    sourceEnvironmentName: RSC_ENV_NAME,
+    sourceEntry: 'index',
+    exportName: 'getServerFnById',
+  } satisfies ViteRscForwardSsrResolverStrategy
+  return {
+    envName: RSC_ENV_NAME,
+    providerEnvironmentName: RSC_ENV_NAME,
+    ssrResolverStrategy,
+    serializationAdapters,
+  }
+}
+export function reactStartRscVitePlugin(): PluginOption {
+  return [
+    // When RSC is enabled, SSR needs noExternal: true to ensure single React instance.
+    // The RSC decoder's dynamic imports for client components can cause module duplication
+    // without this, leading to "Invalid hook call" errors.
+    // We use the top-level `ssr` config option as `environments.ssr.resolve.noExternal`
+    // doesn't have the same effect.
+    {
+      name: 'tanstack-react-start:rsc-ssr-config',
+      config() {
+        return {
+          ssr: {
+            noExternal: true,
+          },
+        }
+      },
+    },
+    {
+      name: 'tanstack-react-start:rsc-env-config',
+      config() {
+        return {
+          rsc: {
+            // Disable @vitejs/plugin-rsc's built-in server handler middleware.
+            // TanStack Start has its own request handling via the SSR environment.
+            serverHandler: false,
+            // Disable CSS link precedence to prevent React 19 SSR suspension
+            // TanStack Start handles CSS preloading via manifest injection instead
+            cssLinkPrecedence: false,
+          },
+          environments: {
+            [RSC_ENV_NAME]: {
+              consumer: 'server',
+              // Force @tanstack packages to be processed by Vite as source code
+              // rather than treated as external modules. This ensures:
+              // 1. createIsomorphicFn transforms are applied
+              // 2. Imports are resolved within the RSC environment context
+              //    with proper react-server conditions and pre-bundled deps
+              resolve: {
+                noExternal: [
+                  '@tanstack/start**',
+                  '@tanstack/react-start',
+                  '@tanstack/react-start-rsc',
+                  '@tanstack/react-router',
+                ],
+              },
+              build: {
+                rollupOptions: {
+                  input: {
+                    index: rscEntryPath,
+                  },
+                },
+              },
+            },
+          },
+        } satisfies UserConfig & {
+          rsc: {
+            serverHandler: false
+            cssLinkPrecedence?: boolean
+          }
+        }
+      },
+    },
+
+    // Runtime bridge into the Vite RSC environment.
+    createVirtualModule({
+      name: 'tanstack-react-start:rsc-runtime-virtual',
+      moduleId: RSC_RUNTIME_VIRTUAL_ID,
+      load() {
+        const envName = this.environment.name
+        if (envName === RSC_ENV_NAME) {
+          return `export { renderToReadableStream, createFromReadableStream, createTemporaryReferenceSet, decodeReply, loadServerAction, decodeAction, decodeFormState } from '@vitejs/plugin-rsc/rsc'`
+        }
+        return `
+export function renderToReadableStream() { throw new Error('renderToReadableStream can only be used in RSC environment'); }
+export function createFromReadableStream() { throw new Error('createFromReadableStream can only be used in RSC environment'); }
+export function createTemporaryReferenceSet() { throw new Error('createTemporaryReferenceSet can only be used in RSC environment'); }
+export function decodeReply() { throw new Error('decodeReply can only be used in RSC environment'); }
+export function loadServerAction() { throw new Error('loadServerAction can only be used in RSC environment'); }
+export function decodeAction() { throw new Error('decodeAction can only be used in RSC environment'); }
+export function decodeFormState() { throw new Error('decodeFormState can only be used in RSC environment'); }
+`
+      },
+    }),
+    createVirtualModule({
+      name: 'tanstack-react-start:rsc-browser-decode-virtual',
+      moduleId: RSC_BROWSER_DECODE_VIRTUAL_ID,
+      load() {
+        return `export { createFromReadableStream, createFromFetch } from '@vitejs/plugin-rsc/browser'`
+      },
+    }),
+    createVirtualModule({
+      name: 'tanstack-react-start:rsc-ssr-decode-virtual',
+      moduleId: RSC_SSR_DECODE_VIRTUAL_ID,
+      load() {
+        return `export { setOnClientReference, createFromReadableStream } from '@vitejs/plugin-rsc/ssr'`
+      },
+    }),
+    createVirtualModule({
+      name: 'tanstack-react-start:rsc-hmr-virtual:dev',
+      moduleId: RSC_HMR_VIRTUAL_ID,
+      apply: 'serve',
+      applyToEnvironment: isClientEnvironment,
+      load() {
+        return `
+export function setupRscHmr() {
+if (!import.meta.hot) {
+  return
+}
+
+  let __invalidateQueued = false
+
+  function __queueInvalidate() {
+    if (__invalidateQueued) return
+    __invalidateQueued = true
+    queueMicrotask(async () => {
+        __invalidateQueued = false
+        try {
+        const router = window.__TSR_ROUTER__
+        if (!router) {
+            console.warn('[rsc:hmr] No router found on window.__TSR_ROUTER__')
+            return
+        }
+        await router.invalidate()
+        } catch (e) {
+        console.warn('[rsc:hmr] Failed to invalidate router:', e)
+        }
+    })
+  }
+
+  import.meta.hot.on('rsc:update', () => {
+    __queueInvalidate()
+  })
+}
+`
+      },
+    }),
+    createVirtualModule({
+      name: 'tanstack-react-start:rsc-hmr-virtual:prod',
+      moduleId: RSC_HMR_VIRTUAL_ID,
+      applyToEnvironment: isClientEnvironment,
+      apply: 'build',
+      load() {
+        return 'export function setupRscHmr() {} '
+      },
+    }),
+  ]
+}

package/src/reactSymbols.ts

@@ -0,0 +1,6 @@
+// Inline React 19 internal $$typeof symbols to avoid depending on `react-is`.
+// `react-is` is CJS-only, causing module resolution failures in strict pnpm
+// setups where it can't be resolved from the consumer's node_modules.
+export const ReactElement = Symbol.for('react.transitional.element')
+export const ReactLazy = Symbol.for('react.lazy')
+export const ReactSuspense = Symbol.for('react.suspense')

package/src/renderServerComponent.stub.ts

@@ -0,0 +1,26 @@
+import type {
+  RenderableServerComponentBuilder,
+  ValidateRenderableServerComponent,
+} from './ServerComponentTypes'
+
+/**
+ * Client stub for renderServerComponent.
+ *
+ * This function should never be called at runtime on the client.
+ * It exists only to satisfy bundler imports in client bundles.
+ * The real implementation only runs inside server functions.
+ */
+export function renderServerComponent<TNode>(
+  _node: ValidateRenderableServerComponent<TNode>,
+): Promise<RenderableServerComponentBuilder<TNode>> {
+  // Unit/type tests import this stub directly and call it.
+  // Avoid throwing in that environment while keeping a hard runtime guard elsewhere.
+  if (process.env.NODE_ENV === 'test') {
+    return Promise.resolve(null as any)
+  }
+
+  throw new Error(
+    'renderServerComponent cannot be called on the client. ' +
+      'This function should only be called inside a server function or route loader.',
+  )
+}

package/src/renderServerComponent.ts

@@ -0,0 +1,110 @@
+import { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'
+import { getRequest } from '@tanstack/start-server-core'
+import { getStartContext } from '@tanstack/start-storage-context'
+
+import { ReplayableStream } from './ReplayableStream'
+import { RENDERABLE_RSC, SERVER_COMPONENT_STREAM } from './ServerComponentTypes'
+import type {
+  AnyRenderableServerComponent,
+  RenderableServerComponentBuilder,
+  ServerComponentStream,
+  ValidateRenderableServerComponent,
+} from './ServerComponentTypes'
+
+import './rscSsrHandler'
+// Import for global declaration side effect
+export type { RscSsrHandler, RscDecodeResult } from './rscSsrHandler'
+
+/**
+ * Renderable RSC handle type - used for serialization detection.
+ */
+
+/**
+ * Type guard for renderable RSC handle.
+ */
+export function isRenderableRscHandle(
+  value: unknown,
+): value is AnyRenderableServerComponent {
+  return (
+    typeof value === 'function' &&
+    SERVER_COMPONENT_STREAM in value &&
+    RENDERABLE_RSC in value &&
+    (value as any)[RENDERABLE_RSC] === true
+  )
+}
+
+/**
+ * Renders a React element to an RSC Flight stream.
+ *
+ * Returns a "renderable proxy" that can be:
+ * - Rendered directly as `{data}` in JSX
+ * - Accessed for nested selections: `{data.foo.bar.Hello}`
+ *
+ * No slot support - for slots use `createCompositeComponent`.
+ *
+ * @example
+ * ```tsx
+ * // In a loader or server function
+ * const data = await renderServerComponent(<MyServerComponent foo="bar" />)
+ *
+ * // In the route component
+ * return (
+ *   <div>
+ *     {data}
+ *     {data.sidebar.Menu}
+ *   </div>
+ * )
+ * ```
+ */
+export async function renderServerComponent<TNode>(
+  node: ValidateRenderableServerComponent<TNode>,
+): Promise<RenderableServerComponentBuilder<TNode>> {
+  // Render the element directly to a Flight stream
+  const flightStream = renderToReadableStream(node)
+
+  // Check if this is an SSR request (router) or a direct server function call
+  const ctx = getStartContext({ throwIfNotFound: false })
+  const isRouterRequest = ctx?.handlerType === 'router'
+  const ssrHandler = globalThis.__RSC_SSR__
+
+  // SSR path: buffer stream for replay, pre-decode for synchronous rendering
+  if (isRouterRequest && ssrHandler) {
+    const signal = getRequest().signal
+    const stream = new ReplayableStream(flightStream, { signal })
+
+    // Pre-decode during loader phase for synchronous SSR rendering
+    const decoded = await ssrHandler.decode(stream)
+    return ssrHandler.createRenderableProxy(
+      stream,
+      decoded,
+    ) as RenderableServerComponentBuilder<TNode>
+  }
+
+  // Server function call path: return a handle for serialization
+  return createRenderableHandle(
+    flightStream,
+  ) as unknown as RenderableServerComponentBuilder<TNode>
+}
+
+/**
+ * Creates a renderable handle for server function responses.
+ * Tagged with RENDERABLE_RSC for the serialization adapter.
+ */
+function createRenderableHandle(
+  flightStream: ReadableStream<Uint8Array>,
+): AnyRenderableServerComponent {
+  const streamWrapper: ServerComponentStream = {
+    createReplayStream: () => flightStream,
+  }
+
+  const stub = function RenderableRscStub(): never {
+    throw new Error(
+      'Renderable RSC from server function cannot be rendered on server. ' +
+        'It should be serialized and sent to the client.',
+    )
+  }
+
+  ;(stub as any)[SERVER_COMPONENT_STREAM] = streamWrapper
+  ;(stub as any)[RENDERABLE_RSC] = true
+  return stub as unknown as AnyRenderableServerComponent
+}

package/src/rscSsrHandler.ts

@@ -0,0 +1,39 @@
+import type {
+  RscSlotUsageEvent,
+  ServerComponentStream,
+} from './ServerComponentTypes'
+
+/**
+ * Result from decoding an RSC stream for SSR.
+ */
+export interface RscDecodeResult {
+  tree: unknown
+  cssHrefs?: Set<string>
+  jsPreloads?: Set<string>
+}
+
+/**
+ * SSR handler interface - registered by serialization.server.ts in SSR environment.
+ * Supports both renderable and composite proxy creation.
+ */
+export interface RscSsrHandler {
+  /** Pre-decode the stream for synchronous SSR rendering */
+  decode: (stream: ServerComponentStream) => Promise<RscDecodeResult>
+  /** Create a renderable proxy (for renderServerComponent) */
+  createRenderableProxy: (
+    stream: ServerComponentStream,
+    decoded: RscDecodeResult,
+  ) => any
+  /** Create a composite proxy (for createCompositeComponent) */
+  createCompositeProxy: (
+    stream: ServerComponentStream,
+    decoded: RscDecodeResult,
+    slotUsagesStream?: ReadableStream<RscSlotUsageEvent>,
+  ) => any
+}
+
+// Single global for SSR environment communication
+declare global {
+  // eslint-disable-next-line no-var
+  var __RSC_SSR__: RscSsrHandler | undefined
+}

package/src/serialization.client.ts

@@ -0,0 +1,43 @@
+import { createSerializationAdapter } from '@tanstack/react-router'
+// RSC HMR setup (dev-only, provided by the active Start bundler adapter).
+import { setupRscHmr } from 'virtual:tanstack-rsc-hmr'
+import {
+  createCompositeFromStream,
+  createRenderableFromStream,
+} from './createServerComponentFromStream'
+import type {
+  AnyCompositeComponent,
+  RscSlotUsageEvent,
+} from './ServerComponentTypes'
+
+if (process.env.NODE_ENV === 'development') {
+  setupRscHmr()
+}
+
+/**
+ * Client-side serialization adapter for RSC (renderable + composite).
+ */
+type SerializedRsc = {
+  kind: 'renderable' | 'composite'
+  stream: ReadableStream<Uint8Array>
+  slotUsagesStream?: ReadableStream<RscSlotUsageEvent>
+}
+
+const adapter = createSerializationAdapter({
+  key: '$RSC',
+  test: (_value: unknown): _value is never => false,
+  toSerializable: (): never => {
+    throw new Error('RSC cannot be serialized on client')
+  },
+  fromSerializable: (value: SerializedRsc): AnyCompositeComponent => {
+    if (value.kind === 'renderable') {
+      return createRenderableFromStream(value.stream)
+    }
+
+    return createCompositeFromStream(value.stream, {
+      slotUsagesStream: value.slotUsagesStream,
+    })
+  },
+})
+
+export const rscSerializationAdapter = () => [adapter]

package/src/serialization.server.ts

@@ -0,0 +1,193 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createSerializationAdapter } from '@tanstack/react-router'
+import { RawStream } from '@tanstack/router-core'
+import { getStartContext } from '@tanstack/start-storage-context'
+import {
+  setOnClientReference,
+  createFromReadableStream as ssrDecode,
+} from 'virtual:tanstack-rsc-ssr-decode'
+import {
+  RENDERABLE_RSC,
+  RSC_SLOT_USAGES_STREAM,
+  SERVER_COMPONENT_STREAM,
+  isServerComponent,
+} from './ServerComponentTypes'
+import { createRscProxy } from './createRscProxy'
+import { awaitLazyElements } from './awaitLazyElements'
+import type {
+  AnyCompositeComponent,
+  ServerComponentStream,
+} from './ServerComponentTypes'
+import type { RscDecodeResult, RscSsrHandler } from './rscSsrHandler'
+
+// ===== SSR Handler Registration =====
+// This handler is registered on globalThis for the RSC environment to access.
+// The RSC env calls these functions during loader execution to pre-decode streams
+// and create renderable proxies.
+//
+// This MUST happen in a module without 'use client' directive.
+// Modules with 'use client' may be transformed to client references in the
+// SSR environment when RSC is enabled, preventing the side effect from running.
+
+// AsyncLocalStorage for decode-scoped CSS collector.
+// Each decode() runs in its own async context with its own collector.
+// The onClientReference callback reads from this to write CSS hrefs.
+const decodeCollectorStorage = new AsyncLocalStorage<Set<string>>()
+const jsCollectorStorage = new AsyncLocalStorage<Set<string>>()
+
+setOnClientReference(
+  ({
+    deps,
+    runtime,
+  }: {
+    deps: { js: Array<string>; css: Array<string> }
+    runtime?: 'rsbuild'
+  }) => {
+    const ctx = getStartContext({ throwIfNotFound: false })
+
+    const cssCollector = decodeCollectorStorage.getStore()
+    if (cssCollector) {
+      for (const href of deps.css) {
+        cssCollector.add(href)
+      }
+    }
+
+    const jsCollector = jsCollectorStorage.getStore()
+    if (jsCollector) {
+      for (const href of deps.js) {
+        jsCollector.add(href)
+      }
+    }
+
+    if (!ctx || runtime === 'rsbuild') return
+
+    if (!ctx.requestAssets) ctx.requestAssets = []
+    const seenHrefs = new Set(
+      ctx.requestAssets
+        .filter((a) => a.tag === 'link' && a.attrs?.href)
+        .map((a) => a.attrs!.href as string),
+    )
+
+    for (const href of deps.js) {
+      if (seenHrefs.has(href)) continue
+      seenHrefs.add(href)
+      ctx.requestAssets.push({
+        tag: 'link',
+        attrs: { rel: 'modulepreload', href },
+      })
+    }
+
+    for (const href of deps.css) {
+      if (seenHrefs.has(href)) continue
+      seenHrefs.add(href)
+      ctx.requestAssets.push({
+        tag: 'link',
+        attrs: { rel: 'preload', href, as: 'style' },
+      })
+    }
+  },
+)
+
+const ssrHandler: RscSsrHandler = {
+  async decode(stream: ServerComponentStream): Promise<RscDecodeResult> {
+    const readableStream = stream.createReplayStream()
+
+    // Create a collector for this decode operation.
+    // Run the decode in an AsyncLocalStorage context so the onClientReference
+    // callback can write to this specific collector even with parallel decodes.
+    const cssCollector = new Set<string>()
+    const jsCollector = new Set<string>()
+
+    return decodeCollectorStorage.run(cssCollector, async () => {
+      return jsCollectorStorage.run(jsCollector, async () => {
+        const tree = await ssrDecode(readableStream)
+        await awaitLazyElements(tree, (href) => {
+          cssCollector.add(href)
+        })
+
+        return {
+          tree,
+          cssHrefs: cssCollector.size > 0 ? cssCollector : undefined,
+          jsPreloads: jsCollector.size > 0 ? jsCollector : undefined,
+        }
+      })
+    })
+  },
+
+  createRenderableProxy(stream, decoded): any {
+    return createRscProxy(() => decoded.tree, {
+      stream,
+      cssHrefs: decoded.cssHrefs,
+      jsPreloads: decoded.jsPreloads,
+      renderable: true,
+    })
+  },
+
+  createCompositeProxy(
+    stream,
+    decoded,
+    slotUsagesStream,
+  ): AnyCompositeComponent {
+    const proxy = createRscProxy(() => decoded.tree, {
+      stream,
+      cssHrefs: decoded.cssHrefs,
+      jsPreloads: decoded.jsPreloads,
+      renderable: false,
+      slotUsagesStream,
+    })
+    return proxy
+  },
+}
+
+// Register SSR handler on globalThis for RSC environment to access.
+globalThis.__RSC_SSR__ = ssrHandler
+
+// ===== End SSR Handler Registration =====
+
+/**
+ * Helper to check if a value is a renderable RSC (from renderServerComponent).
+ * The value can be either an object (proxy target) or a function (stub for server functions).
+ */
+function isRenderableRsc(value: unknown): boolean {
+  if (value === null || value === undefined) return false
+  if (typeof value !== 'object' && typeof value !== 'function') return false
+  return RENDERABLE_RSC in value && (value as any)[RENDERABLE_RSC] === true
+}
+
+/**
+ * Server-side serialization adapter for RSC (renderable + composite).
+ */
+const adapter = createSerializationAdapter({
+  key: '$RSC',
+  test: (value: unknown): value is AnyCompositeComponent => {
+    return isServerComponent(value)
+  },
+  toSerializable: (component: AnyCompositeComponent) => {
+    const stream = component[SERVER_COMPONENT_STREAM]!.createReplayStream()
+
+    const kind = isRenderableRsc(component) ? 'renderable' : 'composite'
+
+    const slotUsagesStream =
+      kind === 'composite' &&
+      process.env.NODE_ENV === 'development' &&
+      RSC_SLOT_USAGES_STREAM in component
+        ? ((component as any)[RSC_SLOT_USAGES_STREAM] as unknown as
+            | ReadableStream<any>
+            | undefined)
+        : undefined
+
+    return {
+      kind,
+      stream: new RawStream(stream, { hint: 'text' }),
+      slotUsagesStream,
+    }
+  },
+  fromSerializable: (): never => {
+    throw new Error('Server should never deserialize RSC data')
+  },
+})
+
+/**
+ * Factory function for server-side RSC serialization adapter.
+ */
+export const rscSerializationAdapter = () => [adapter]