@tanstack/react-start-rsc 0.0.0

package/src/createRscProxy.tsx

@@ -0,0 +1,294 @@
+'use client'
+
+import { createElement } from 'react'
+import { RscNodeRenderer } from './RscNodeRenderer'
+import {
+  RENDERABLE_RSC,
+  RSC_PROXY_GET_TREE,
+  RSC_PROXY_PATH,
+  RSC_SLOT_USAGES,
+  RSC_SLOT_USAGES_STREAM,
+  SERVER_COMPONENT_CSS_HREFS,
+  SERVER_COMPONENT_JS_PRELOADS,
+  SERVER_COMPONENT_STREAM,
+} from './ServerComponentTypes'
+import type { RscSlotUsageEvent } from './ServerComponentTypes'
+
+export interface RscProxyOptions {
+  stream?: unknown // The stream to attach for serialization
+  cssHrefs?: ReadonlySet<string> // CSS hrefs collected from the RSC stream
+  jsPreloads?: ReadonlySet<string> // JS hrefs collected from the RSC stream
+  renderable?: boolean // If true, proxy masquerades as React element
+  slotUsagesStream?: ReadableStream<RscSlotUsageEvent> // Dev only: slot usage event stream
+}
+
+/**
+ * Creates a recursive Proxy for RSC data.
+ *
+ * If `renderable: true`, returns a React element that can be rendered as `{data}`.
+ * The element also has proxy-like behavior for nested access like `data.foo.bar`.
+ *
+ * If `renderable: false` (default), the proxy is NOT directly renderable and
+ * must be used with `<CompositeComponent src={...} />`.
+ */
+export function createRscProxy<T>(
+  getTree: () => T,
+  options: RscProxyOptions = {},
+): any {
+  if (options.renderable) {
+    // For renderable mode, create a real React element with proxy access
+    return createRenderableElement(
+      getTree,
+      [],
+      options.stream,
+      options.cssHrefs,
+      options.jsPreloads,
+    )
+  }
+  let slotUsages: Array<RscSlotUsageEvent> | undefined = undefined
+
+  if (
+    process.env.NODE_ENV === 'development' &&
+    typeof window !== 'undefined' &&
+    options.slotUsagesStream
+  ) {
+    slotUsages = []
+    void consumeSlotUsages(options.slotUsagesStream, slotUsages)
+  }
+
+  // Non-renderable mode: plain proxy
+  return createRscProxyWithPath(
+    getTree,
+    [],
+    options.stream,
+    options.cssHrefs,
+    options.jsPreloads,
+    slotUsages,
+    options.slotUsagesStream,
+  )
+}
+
+/**
+ * Creates a React element that's also a Proxy for nested access.
+ * This is used by renderable RSCs so they work as both {data} and {data.foo.bar}.
+ */
+type CreateProxyOptions = {
+  getTree: () => unknown
+  path: Array<string>
+  stream: unknown | undefined
+  cssHrefs: ReadonlySet<string> | undefined
+  jsPreloads: ReadonlySet<string> | undefined
+  renderable: boolean
+  slotUsages: Array<RscSlotUsageEvent> | undefined
+  slotUsagesStream: ReadableStream<RscSlotUsageEvent> | undefined
+}
+
+const UNHANDLED = Symbol('tanstack.rsc.proxy.unhandled')
+
+function handleProxyTrap(
+  kind: 'get' | 'has',
+  prop: PropertyKey,
+  options: CreateProxyOptions,
+): unknown | boolean | typeof UNHANDLED {
+  switch (prop) {
+    // Seroval (>=1.5) uses string sentinels and `in` checks for internal types.
+    // These proxies must never look like streams/sequences.
+    case '__SEROVAL_STREAM__':
+    case '__SEROVAL_SEQUENCE__':
+      return kind === 'get' ? undefined : false
+
+    // Seroval >=1.5 also checks iterability via `Symbol.iterator in value`.
+    case Symbol.iterator:
+    case Symbol.asyncIterator:
+      return kind === 'get' ? undefined : false
+
+    // Our proxy branding/properties
+    case SERVER_COMPONENT_STREAM:
+      return kind === 'get' ? options.stream : options.stream !== undefined
+    case SERVER_COMPONENT_CSS_HREFS:
+      return kind === 'get' ? options.cssHrefs : options.cssHrefs !== undefined
+    case SERVER_COMPONENT_JS_PRELOADS:
+      return kind === 'get'
+        ? options.jsPreloads
+        : options.jsPreloads !== undefined
+    case RSC_PROXY_GET_TREE:
+      return kind === 'get' ? options.getTree : true
+    case RSC_PROXY_PATH:
+      return kind === 'get' ? options.path : true
+    case RENDERABLE_RSC:
+      return kind === 'get' ? options.renderable : true
+    case RSC_SLOT_USAGES:
+      return kind === 'get'
+        ? options.slotUsages
+        : options.slotUsages !== undefined
+
+    case RSC_SLOT_USAGES_STREAM:
+      return kind === 'get'
+        ? options.slotUsagesStream
+        : options.slotUsagesStream !== undefined
+
+    // Avoid promise-like checks
+    case 'then':
+      return kind === 'get' ? undefined : UNHANDLED
+
+    // Avoid breaking primitive coercion (eg String(proxy)).
+    // Without these, nested-selection proxies can shadow these keys and
+    // cause `Cannot convert object to primitive value` errors.
+    case 'toString':
+      return kind === 'get' ? Object.prototype.toString : UNHANDLED
+    case 'valueOf':
+      return kind === 'get' ? Object.prototype.valueOf : UNHANDLED
+    case 'constructor':
+      return kind === 'get' ? Object : UNHANDLED
+  }
+
+  // Non-renderable proxies claim all string keys exist for nested selection,
+  // but symbol presence checks should be accurate.
+  if (typeof prop === 'symbol') {
+    return kind === 'get' ? undefined : false
+  }
+
+  return UNHANDLED
+}
+
+function createRscProxyInternal(options: CreateProxyOptions): any {
+  // Per-proxy cache so repeated property access is referentially stable.
+  const childCache = new Map<string, any>()
+
+  const getChild = (key: string) => {
+    const cached = childCache.get(key)
+    if (cached) return cached
+
+    const next = createRscProxyInternal({
+      ...options,
+      path: [...options.path, key],
+    })
+    childCache.set(key, next)
+    return next
+  }
+
+  const dataProxy = options.renderable
+    ? createRscProxyInternal({ ...options, renderable: false })
+    : undefined
+
+  // Use a React element (renderable) or plain object (non-renderable) as Proxy target.
+  const proxyTarget = options.renderable
+    ? createElement(RscNodeRenderer, { data: dataProxy })
+    : ({} as any)
+
+  return new Proxy(proxyTarget, {
+    get(target, prop) {
+      const handled = handleProxyTrap('get', prop, options)
+      if (handled !== UNHANDLED) return handled
+
+      if (options.renderable) {
+        // Proxy invariants: if target has a non-configurable, read-only property,
+        // we must return the *exact* value for that property.
+        if (prop === 'props') {
+          return target.props
+        }
+
+        if (prop === 'data') {
+          return dataProxy
+        }
+
+        if (prop in target) {
+          return target[prop]
+        }
+      }
+
+      return getChild(String(prop))
+    },
+
+    has(target, prop) {
+      const handled = handleProxyTrap('has', prop, options)
+      if (handled !== UNHANDLED) return handled as boolean
+
+      if (options.renderable) {
+        if (prop in target) return true
+        if (typeof prop === 'string') return true
+        return false
+      }
+
+      // Allow any property access for nested selection.
+      return true
+    },
+
+    getPrototypeOf(target) {
+      return options.renderable
+        ? Object.getPrototypeOf(target)
+        : Object.prototype
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      return options.renderable
+        ? Object.getOwnPropertyDescriptor(target, prop)
+        : undefined
+    },
+
+    ownKeys(target) {
+      return options.renderable ? Reflect.ownKeys(target) : []
+    },
+  })
+}
+
+/**
+ * Creates a React element that's also a Proxy for nested access.
+ * This is used by renderable RSCs so they work as both {data} and {data.foo.bar}.
+ */
+function createRenderableElement(
+  getTree: () => unknown,
+  path: Array<string>,
+  stream: unknown | undefined,
+  cssHrefs: ReadonlySet<string> | undefined,
+  jsPreloads: ReadonlySet<string> | undefined,
+): any {
+  return createRscProxyInternal({
+    getTree,
+    path,
+    stream,
+    cssHrefs,
+    jsPreloads,
+    renderable: true,
+    slotUsages: undefined,
+    slotUsagesStream: undefined,
+  })
+}
+
+function createRscProxyWithPath(
+  getTree: () => unknown,
+  path: Array<string>,
+  stream: unknown | undefined,
+  cssHrefs: ReadonlySet<string> | undefined,
+  jsPreloads: ReadonlySet<string> | undefined,
+  slotUsages: Array<RscSlotUsageEvent> | undefined,
+  slotUsagesStream: ReadableStream<RscSlotUsageEvent> | undefined,
+): any {
+  return createRscProxyInternal({
+    getTree,
+    path,
+    stream,
+    cssHrefs,
+    jsPreloads,
+    renderable: false,
+    slotUsages,
+    slotUsagesStream,
+  })
+}
+
+async function consumeSlotUsages(
+  stream: ReadableStream<RscSlotUsageEvent>,
+  slotUsages: Array<RscSlotUsageEvent>,
+): Promise<void> {
+  try {
+    const reader = stream.getReader()
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      if (!value.slot) continue
+      slotUsages.push(value)
+    }
+  } catch {
+    // Ignore - dev-only best effort
+  }
+}

package/src/createServerComponentFromStream.ts

@@ -0,0 +1,105 @@
+'use client'
+
+import { use } from 'react'
+import { trackPostProcessPromise } from '@tanstack/start-client-core'
+import { createFromReadableStream as browserDecode } from 'virtual:tanstack-rsc-browser-decode'
+
+import { awaitLazyElements } from './awaitLazyElements'
+import { createRscProxy } from './createRscProxy'
+import type {
+  AnyCompositeComponent,
+  RscSlotUsageEvent,
+  ServerComponentStream,
+} from './ServerComponentTypes'
+
+/**
+ * Creates a renderable RSC proxy from a raw Flight stream.
+ * Client-side only - used by the client serialization adapter for `renderServerComponent`.
+ *
+ * Returns a Proxy that:
+ * - Can be rendered directly as `{data}` in JSX
+ * - Supports nested access: `{data.foo.bar}`
+ * - Masquerades as a React element
+ */
+export function createRenderableFromStream(
+  stream: ReadableStream<Uint8Array>,
+): any {
+  const { getTree, streamWrapper, cssHrefs } = setupStreamDecode(stream)
+
+  return createRscProxy(getTree, {
+    stream: streamWrapper,
+    cssHrefs,
+    renderable: true,
+  })
+}
+
+/**
+ * Creates a composite RSC proxy from a raw Flight stream.
+ * Client-side only - used by the client serialization adapter for `createCompositeComponent`.
+ *
+ * Returns a Proxy that:
+ * - NOT directly renderable
+ * - Supports nested access: `src.foo.bar`
+ * - Must be rendered via `<CompositeComponent src={...} />`
+ */
+export function createCompositeFromStream(
+  stream: ReadableStream<Uint8Array>,
+  options?: {
+    slotUsagesStream?: ReadableStream<RscSlotUsageEvent>
+  },
+): AnyCompositeComponent {
+  const { getTree, streamWrapper, cssHrefs } = setupStreamDecode(stream)
+
+  return createRscProxy(getTree, {
+    stream: streamWrapper,
+    cssHrefs,
+    renderable: false,
+    slotUsagesStream: options?.slotUsagesStream,
+  })
+}
+
+/**
+ * Shared stream decode setup for both renderable and composite.
+ */
+function setupStreamDecode(stream: ReadableStream<Uint8Array>): {
+  getTree: () => unknown
+  streamWrapper: ServerComponentStream
+  cssHrefs: Set<string> | undefined
+} {
+  // Start decoding eagerly during deserialization
+  const decodeThenable = browserDecode(stream)
+  const cssHrefs = new Set<string>()
+
+  // Synchronous cache for the decoded tree.
+  let cachedTree: unknown = undefined
+  let cacheReady = false
+
+  // Promise for the tree with lazy elements awaited.
+  const transformedTreePromise = Promise.resolve(decodeThenable).then(
+    async (result) => {
+      await awaitLazyElements(result, (href) => {
+        cssHrefs.add(href)
+      })
+      cachedTree = result
+      cacheReady = true
+      return result
+    },
+  )
+
+  // Track the lazy element loading - prevents flash
+  trackPostProcessPromise(transformedTreePromise)
+
+  const streamWrapper: ServerComponentStream = {
+    createReplayStream: () => stream,
+  }
+
+  const getTree = () => {
+    if (cacheReady) return cachedTree
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    return use(transformedTreePromise)
+  }
+
+  return { getTree, streamWrapper, cssHrefs }
+}
+// Legacy export for backwards compatibility during migration
+export const createServerComponentFromStream = createCompositeFromStream

package/src/entry/rsc.tsx

@@ -0,0 +1,23 @@
+/**
+ * Shared RSC (React Server Components) entry point.
+ *
+ * This file exports the functions needed for the active RSC environment:
+ * - getServerFnById: Resolves server functions by their encoded ID
+ * - render: Renders a React node to an RSC Flight stream
+ */
+
+import { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'
+import type React from 'react'
+
+// Re-export getServerFnById from the virtual module which handles both dev and production
+// In dev: dynamic import with base64url-decoded file path
+// In production: manifest-based lookup with bundled chunks
+export { getServerFnById } from '#tanstack-start-server-fn-resolver'
+
+/**
+ * Renders a React node to an RSC Flight stream.
+ * Used internally for streaming server component output.
+ */
+export function render(node: React.ReactNode): ReadableStream<Uint8Array> {
+  return renderToReadableStream(node)
+}

package/src/entry/virtual-modules.d.ts

@@ -0,0 +1,12 @@
+// Type declarations for virtual modules used in RSC entry
+// These modules are provided by the active bundler adapter at runtime
+
+declare module '#tanstack-start-server-fn-resolver' {
+  export type ServerFnLookupAccess = { origin: 'client' } | { origin: 'server' }
+
+  export type ServerFn = (...args: Array<any>) => Promise<any>
+  export function getServerFnById(
+    id: string,
+    access: ServerFnLookupAccess,
+  ): Promise<ServerFn>
+}

package/src/flight.rsc.ts

@@ -0,0 +1,17 @@
+/**
+ * Low-level Flight stream API for RSC (React Server Components) environment.
+ *
+ * This exports renderToReadableStream which generates a Flight stream from
+ * React elements. Only available in RSC context (react-server condition).
+ *
+ * @example
+ * ```tsx
+ * import { renderToReadableStream } from '@tanstack/react-start/rsc'
+ *
+ * const stream = renderToReadableStream(<MyServerComponent />)
+ * return new Response(stream, {
+ *   headers: { 'Content-Type': 'text/x-component' }
+ * })
+ * ```
+ */
+export { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'

package/src/flight.stub.ts

@@ -0,0 +1,15 @@
+/**
+ * Client stub for renderToReadableStream.
+ *
+ * This function should never be called at runtime on the client.
+ * It exists only to provide types for bundler imports in client bundles.
+ * The real implementation only runs inside RSC context (server functions).
+ */
+export function renderToReadableStream(
+  _node: React.ReactNode,
+): ReadableStream<Uint8Array> {
+  throw new Error(
+    'renderToReadableStream cannot be called on the client. ' +
+      'This function should only be called inside RSC context (server functions).',
+  )
+}

package/src/flight.ts

@@ -0,0 +1,68 @@
+/**
+ * Low-level Flight stream APIs for decoding RSC streams.
+ *
+ * These functions provide direct access to RSC Flight stream decoding,
+ * allowing advanced use cases like:
+ * - Server functions returning raw Flight Response
+ * - API routes streaming Flight payloads
+ * - Custom Flight stream handling via RawStream
+ *
+ * `createFromReadableStream` works in both SSR and browser contexts.
+ * `createFromFetch` is browser-only.
+ *
+ * NOTE: Dynamic imports keep decode initialisation runtime-specific. The
+ * concrete implementation comes from bundler-owned virtual modules.
+ */
+
+import {
+  createClientOnlyFn,
+  createIsomorphicFn,
+} from '@tanstack/start-fn-stubs'
+
+/**
+ * Decode a Flight stream into React elements.
+ * Works in both SSR and browser contexts.
+ *
+ * @example
+ * ```tsx
+ * const rawStream = await getRscRawStream()
+ * const tree = await createFromReadableStream(rawStream)
+ * return <>{tree}</>
+ * ```
+ */
+export const createFromReadableStream = createIsomorphicFn()
+  .server(
+    async (stream: ReadableStream<Uint8Array>): Promise<React.ReactNode> => {
+      const { createFromReadableStream: decode } =
+        await import('virtual:tanstack-rsc-ssr-decode')
+      return decode(stream) as React.ReactNode
+    },
+  )
+  .client(
+    async (stream: ReadableStream<Uint8Array>): Promise<React.ReactNode> => {
+      const { createFromReadableStream: decode } =
+        await import('virtual:tanstack-rsc-browser-decode')
+      return decode(stream)
+    },
+  )
+
+/**
+ * Decode a Flight stream from a fetch Response.
+ * Browser only - will throw if called on the server.
+ *
+ * @example
+ * ```tsx
+ * // From server function returning raw Response
+ * const tree = await createFromFetch(getFlightResponse())
+ *
+ * // From API route
+ * const tree = await createFromFetch(fetch('/api/rsc-flight'))
+ * ```
+ */
+export const createFromFetch = createClientOnlyFn(
+  async (fetchPromise: Promise<Response>): Promise<React.ReactNode> => {
+    const { createFromFetch: decode } =
+      await import('virtual:tanstack-rsc-browser-decode')
+    return decode(fetchPromise)
+  },
+)

package/src/global.d.ts

@@ -0,0 +1,75 @@
+/// <reference types="vite/client" />
+
+/**
+ * Type declarations for virtual:tanstack-rsc-runtime
+ *
+ * This virtual module is provided by the active Start bundler adapter
+ * and re-exports RSC runtime functions from that adapter's Flight runtime.
+ *
+ * Using a virtual module allows the imports to be resolved at runtime within
+ * the correct server environment context (react-server conditions).
+ */
+declare module 'virtual:tanstack-rsc-runtime' {
+  export function renderToReadableStream<T>(
+    data: T,
+    options?: object,
+  ): ReadableStream<Uint8Array>
+  export function createFromReadableStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: object,
+  ): Promise<T>
+  export function createTemporaryReferenceSet(): object
+  export function decodeReply<T = unknown>(
+    body: string | FormData,
+    options?: object,
+  ): Promise<T>
+  export function loadServerAction(id: string): Promise<(...args: any) => any>
+  export function decodeAction<T = unknown>(
+    body: FormData,
+    serverManifest?: unknown,
+  ): Promise<() => T>
+  export function decodeFormState<T = unknown>(
+    actionResult: T,
+    body: FormData,
+    serverManifest?: unknown,
+  ): Promise<unknown>
+}
+
+declare module 'virtual:tanstack-rsc-browser-decode' {
+  export function createFromReadableStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: object,
+  ): Promise<T>
+  export function createFromFetch<T = unknown>(
+    response: Promise<Response>,
+  ): Promise<T>
+}
+
+declare module 'virtual:tanstack-rsc-ssr-decode' {
+  export function setOnClientReference(
+    callback:
+      | ((reference: {
+          id: string
+          deps: { js: Array<string>; css: Array<string> }
+          runtime?: 'rsbuild'
+        }) => void)
+      | undefined,
+  ): void
+  export function createFromReadableStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: object,
+  ): Promise<T>
+}
+
+/**
+ * Type declarations for virtual:tanstack-rsc-hmr
+ *
+ * This virtual module is provided by the active Start bundler adapter
+ * and sets up the RSC HMR listener in dev mode. It listens for 'rsc:update'
+ * events and invalidates the router to refetch server components.
+ *
+ * In production builds, this module is empty.
+ */
+declare module 'virtual:tanstack-rsc-hmr' {
+  export function setupRscHmr(): void
+}

package/src/index.rsc.ts

@@ -0,0 +1,25 @@
+// Server-side exports (react-server condition)
+// This file is used when importing from RSC (React Server Components) context
+
+// Types are always available
+export type { AnyCompositeComponent } from './ServerComponentTypes'
+
+// New API: renderServerComponent - renders element to renderable proxy
+export { renderServerComponent } from './renderServerComponent.js'
+
+// New API: createCompositeComponent - creates composite with slot support
+export { createCompositeComponent } from './createCompositeComponent.js'
+
+// Renderer for composite RSC data (client/SSR)
+export { CompositeComponent } from './CompositeComponent.js'
+
+// Low-level Flight stream API (RSC only)
+export { renderToReadableStream } from './flight.rsc.js'
+
+// Low-level Flight stream APIs (also available in RSC for decode operations)
+export { createFromReadableStream, createFromFetch } from './flight'
+
+// Note: rscSerializationAdapter is intentionally NOT exported here.
+// It uses createSerializationAdapter from react-router which is marked as
+// client-only in RSC environment. The adapter is only needed by SSR/client
+// for serializing/deserializing server components, not by RSC itself.

package/src/index.ts

@@ -0,0 +1,26 @@
+// Default exports (used by client bundles and SSR)
+// This file is used when importing outside of RSC (React Server Components) context
+
+// Types are always available
+export type { AnyCompositeComponent } from './ServerComponentTypes'
+
+// CSS hrefs symbol for type-safe access
+export { SERVER_COMPONENT_CSS_HREFS } from './ServerComponentTypes'
+
+// Stubs for RSC-only functions - throw if called outside RSC context
+export { renderServerComponent } from './renderServerComponent.stub.js'
+export { createCompositeComponent } from './createCompositeComponent.stub.js'
+
+// Renderer for composite RSC data (client/SSR)
+export { CompositeComponent } from './CompositeComponent.js'
+
+// Low-level Flight stream APIs (client/SSR)
+export { createFromReadableStream, createFromFetch } from './flight'
+
+// Stub for renderToReadableStream - throws if called outside RSC context
+export { renderToReadableStream } from './flight.stub.js'
+
+// Note: rscSerializationAdapter is intentionally NOT exported here.
+// It imports virtual:tanstack-rsc-hmr which is client-only (not available in SSR).
+// Import directly from '@tanstack/react-start-rsc/serialization.client' or
+// '@tanstack/react-start-rsc/serialization.server' as needed.