@tanstack/react-start-rsc 0.0.36 → 0.0.37

package/dist/esm/createCompositeComponent.js

@@ -1,5 +1,6 @@
 import { RSC_SLOT_USAGES_STREAM, SERVER_COMPONENT_STREAM } from "./ServerComponentTypes.js";
 import { ReplayableStream } from "./ReplayableStream.js";
+import { createRscCssEnvelope } from "./rscCssEnvelope.js";
 import { sanitizeSlotArgs } from "./slotUsageSanitizer.js";
 import { ClientSlot } from "./ClientSlot.js";
 import { createElement } from "react";
@@ -37,7 +38,7 @@ import { getStartContext } from "@tanstack/start-storage-context";
 * )
 * ```
 */
-async function createCompositeComponent(component) {
+async function createCompositeComponent(component, options) {
 	const isDev = process.env.NODE_ENV === "development";
 	const slotUsagesEmitter = isDev ? createReadableStreamEmitter() : null;
 	const { proxy: proxyProps } = createSlotProxy({ onSlotCall: slotUsagesEmitter ? (name, args) => {
@@ -48,7 +49,7 @@ async function createCompositeComponent(component) {
 		});
 	} : void 0 });
 	async function ServerComponentWrapper() {
-		return component(proxyProps);
+		return createRscCssEnvelope(await component(proxyProps), options);
 	}
 	const flightStream = renderToReadableStream(createElement(ServerComponentWrapper));
 	const isRouterRequest = getStartContext({ throwIfNotFound: false })?.handlerType === "router";

package/dist/esm/createCompositeComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"createCompositeComponent.js","names":[],"sources":["../../src/createCompositeComponent.ts"],"sourcesContent":["import { createElement } from 'react'\nimport { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'\nimport { getRequest } from '@tanstack/start-server-core'\nimport { getStartContext } from '@tanstack/start-storage-context'\nimport { sanitizeSlotArgs } from './slotUsageSanitizer'\nimport { ReplayableStream } from './ReplayableStream'\nimport { ClientSlot } from './ClientSlot'\nimport {\n  RSC_SLOT_USAGES_STREAM,\n  SERVER_COMPONENT_STREAM,\n} from './ServerComponentTypes'\nimport type {\n  AnyCompositeComponent,\n  CompositeComponentResult,\n  RscSlotUsageEvent,\n  ServerComponentStream,\n  ValidateCompositeComponent,\n} from './ServerComponentTypes'\n\nimport './rscSsrHandler' // Import for global declaration side effect\n\n/**\n * Creates a composite server component with slot support.\n *\n * Supports returning:\n * - A ReactNode directly\n * - An object structure with ReactNodes: accessed as `src.Foo`\n * - Nested structures: accessed as `src.x.Bar`\n *\n * Props that are functions become slots - they render as ClientSlot placeholders\n * in the RSC output, filled in by the consumer with actual implementations.\n *\n * The returned value is NOT directly renderable. Use `<CompositeComponent src={...} />`.\n *\n * @example\n * ```tsx\n * const src = await createCompositeComponent((props) => (\n *   <div>\n *     <header>{props.header('Dashboard')}</header>\n *     <main>{props.children}</main>\n *   </div>\n * ))\n *\n * // In route component\n * return (\n *   <CompositeComponent src={src} header={(title) => <h1>{title}</h1>}>\n *     <p>Main content</p>\n *   </CompositeComponent>\n * )\n * ```\n */\nexport async function createCompositeComponent<TComp>(\n  component: ValidateCompositeComponent<TComp>,\n): Promise<CompositeComponentResult<TComp>> {\n  const isDev = process.env.NODE_ENV === 'development'\n\n  // Dev-only: stream slot usage events (slot + raw args)\n  const slotUsagesEmitter = isDev\n    ? createReadableStreamEmitter<RscSlotUsageEvent>()\n    : null\n\n  // Create a wrapper component that will be rendered inside React's Flight context.\n  // This ensures React.cache works properly since the component is called during\n  // renderToReadableStream's render phase, not before it.\n  const { proxy: proxyProps } = createSlotProxy<{}>({\n    onSlotCall: slotUsagesEmitter\n      ? (name, args) => {\n          const sanitizedArgs = sanitizeSlotArgs(args)\n          slotUsagesEmitter.emit({\n            slot: name,\n            args: sanitizedArgs.length ? sanitizedArgs : undefined,\n          })\n        }\n      : undefined,\n  })\n\n  // Wrapper that renders the user's component inside Flight render context\n  async function ServerComponentWrapper() {\n    return (component as React.FC)(proxyProps)\n  }\n\n  // Render using createElement so React calls our component during Flight rendering\n  // This is critical for React.cache to work - the component must be invoked\n  // during renderToReadableStream's execution, not before\n  const flightStream = renderToReadableStream(\n    createElement(ServerComponentWrapper),\n  )\n\n  // Check if this is an SSR request (router) or a direct server function call\n  const ctx = getStartContext({ throwIfNotFound: false })\n  const isRouterRequest = ctx?.handlerType === 'router'\n  const ssrHandler = globalThis.__RSC_SSR__\n\n  // SSR path: buffer stream for replay, pre-decode for synchronous rendering\n  if (isRouterRequest && ssrHandler) {\n    const signal = getRequest().signal\n    const stream = new ReplayableStream(flightStream, { signal })\n\n    // Pre-decode during loader phase for synchronous SSR rendering\n    const decoded = await ssrHandler.decode(stream)\n\n    // For SSR we know decode fully consumed the Flight stream.\n    slotUsagesEmitter?.close()\n\n    return ssrHandler.createCompositeProxy(\n      stream,\n      decoded,\n      slotUsagesEmitter?.stream,\n    ) as CompositeComponentResult<TComp>\n  }\n\n  // Server function call path:\n  // The serialization adapter will stream to the client.\n  const monitoredFlightStream =\n    isDev && slotUsagesEmitter\n      ? wrapReadableStream(flightStream, {\n          onDone: () => {\n            slotUsagesEmitter.close()\n          },\n          onCancel: () => {\n            slotUsagesEmitter.close()\n          },\n          onError: () => {\n            slotUsagesEmitter.close()\n          },\n        })\n      : flightStream\n\n  return createCompositeHandle(monitoredFlightStream, {\n    slotUsagesStream: slotUsagesEmitter?.stream,\n  }) as CompositeComponentResult<TComp>\n}\n\n/**\n * Creates a composite handle for server function responses.\n * No proxy needed - the client will decode and create its own proxy.\n */\nfunction createCompositeHandle(\n  flightStream: ReadableStream<Uint8Array>,\n  options?: {\n    slotUsagesStream?: ReadableStream<RscSlotUsageEvent>\n  },\n): AnyCompositeComponent {\n  // Simple single-use stream wrapper. For server function calls, the stream\n  // is consumed exactly once by the serialization adapter for transport.\n  const streamWrapper: ServerComponentStream = {\n    createReplayStream: () => flightStream,\n  }\n\n  // Create a stub function with the stream attached for serialization.\n  // This will never be rendered directly - it goes through serialization\n  // which extracts the stream and sends it to the client.\n  const stub = function CompositeComponentStub(): never {\n    throw new Error(\n      'CompositeComponent from server function cannot be rendered on server. ' +\n        'It should be serialized and sent to the client.',\n    )\n  }\n\n  ;(stub as any)[SERVER_COMPONENT_STREAM] = streamWrapper\n  // Note: RENDERABLE_RSC is not set (or implicitly false), indicating this is a composite component\n\n  if (options?.slotUsagesStream) {\n    ;(stub as any)[RSC_SLOT_USAGES_STREAM] = options.slotUsagesStream\n  }\n\n  return stub as unknown as AnyCompositeComponent\n}\n\n/**\n * Base slot props type - functions that become ClientSlot placeholders\n */\ninterface SlotPropsBase {\n  [key: string]:\n    | ((...args: Array<any>) => React.ReactNode)\n    | React.ReactNode\n    | undefined\n  children?: React.ReactNode\n}\n\ninterface SlotProxyResult<TSlotProps extends object> {\n  proxy: TSlotProps & SlotPropsBase\n}\n\n/**\n * Proxy that turns property access into ClientSlot renders.\n * Also tracks accessed slot names for devtools.\n */\nfunction createSlotProxy<TSlotProps extends object>(options?: {\n  onSlotCall?: (name: string, args: Array<any>) => void\n}): SlotProxyResult<TSlotProps> {\n  const cache = new Map<string, (...args: Array<any>) => React.ReactNode>()\n\n  const proxy = new Proxy({} as TSlotProps & SlotPropsBase, {\n    get(_target, prop) {\n      if (prop === 'then' || typeof prop !== 'string') return undefined\n\n      if (prop === 'children') {\n        options?.onSlotCall?.('children', [])\n        return createElement(ClientSlot, { slot: 'children', args: [] })\n      }\n\n      let fn = cache.get(prop)\n      if (!fn) {\n        fn = (...args: Array<any>) => {\n          options?.onSlotCall?.(prop, args)\n          return createElement(ClientSlot, { slot: prop, args })\n        }\n        cache.set(prop, fn)\n      }\n      return fn\n    },\n  })\n\n  return {\n    proxy,\n  }\n}\n\nfunction createReadableStreamEmitter<T>(): {\n  stream: ReadableStream<T>\n  emit: (value: T) => void\n  close: () => void\n} {\n  let closed = false\n  const queue: Array<T> = []\n  let controller: ReadableStreamDefaultController<T> | null = null\n\n  const stream = new ReadableStream<T>({\n    start(ctrl) {\n      controller = ctrl\n      for (const value of queue) {\n        try {\n          ctrl.enqueue(value)\n        } catch {\n          // Ignore\n        }\n      }\n      queue.length = 0\n      if (closed) {\n        try {\n          ctrl.close()\n        } catch {\n          // Ignore\n        }\n      }\n    },\n    cancel() {\n      closed = true\n      controller = null\n      queue.length = 0\n    },\n  })\n\n  const emit = (value: T) => {\n    if (closed) return\n    if (!controller) {\n      queue.push(value)\n      return\n    }\n    try {\n      controller.enqueue(value)\n    } catch {\n      // Ignore\n    }\n  }\n\n  const close = () => {\n    if (closed) return\n    closed = true\n    if (controller) {\n      try {\n        controller.close()\n      } catch {\n        // Ignore\n      }\n      controller = null\n    }\n  }\n\n  return { stream, emit, close }\n}\n\nfunction wrapReadableStream<T>(\n  source: ReadableStream<T>,\n  handlers: {\n    onDone?: () => void\n    onCancel?: () => void\n    onError?: () => void\n  },\n): ReadableStream<T> {\n  const reader = source.getReader()\n  let finished = false\n\n  const finish = () => {\n    if (finished) return\n    finished = true\n    handlers.onDone?.()\n    try {\n      reader.releaseLock()\n    } catch {\n      // Ignore\n    }\n  }\n\n  return new ReadableStream<T>({\n    async pull(controller) {\n      try {\n        const { value, done } = await reader.read()\n        if (done) {\n          controller.close()\n          finish()\n          return\n        }\n        controller.enqueue(value)\n      } catch (err) {\n        try {\n          controller.error(err)\n        } catch {\n          // Ignore\n        }\n        handlers.onError?.()\n        finish()\n      }\n    },\n    async cancel(reason) {\n      handlers.onCancel?.()\n      try {\n        await reader.cancel(reason)\n      } catch {\n        // Ignore\n      }\n      finish()\n    },\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,eAAsB,yBACpB,WAC0C;CAC1C,MAAM,QAAA,QAAA,IAAA,aAAiC;CAGvC,MAAM,oBAAoB,QACtB,6BAAgD,GAChD;CAKJ,MAAM,EAAE,OAAO,eAAe,gBAAoB,EAChD,YAAY,qBACP,MAAM,SAAS;EACd,MAAM,gBAAgB,iBAAiB,KAAK;AAC5C,oBAAkB,KAAK;GACrB,MAAM;GACN,MAAM,cAAc,SAAS,gBAAgB,KAAA;GAC9C,CAAC;KAEJ,KAAA,GACL,CAAC;CAGF,eAAe,yBAAyB;AACtC,SAAQ,UAAuB,WAAW;;CAM5C,MAAM,eAAe,uBACnB,cAAc,uBAAuB,CACtC;CAID,MAAM,kBADM,gBAAgB,EAAE,iBAAiB,OAAO,CAAC,EAC1B,gBAAgB;CAC7C,MAAM,aAAa,WAAW;AAG9B,KAAI,mBAAmB,YAAY;EACjC,MAAM,SAAS,YAAY,CAAC;EAC5B,MAAM,SAAS,IAAI,iBAAiB,cAAc,EAAE,QAAQ,CAAC;EAG7D,MAAM,UAAU,MAAM,WAAW,OAAO,OAAO;AAG/C,qBAAmB,OAAO;AAE1B,SAAO,WAAW,qBAChB,QACA,SACA,mBAAmB,OACpB;;AAoBH,QAAO,sBAdL,SAAS,oBACL,mBAAmB,cAAc;EAC/B,cAAc;AACZ,qBAAkB,OAAO;;EAE3B,gBAAgB;AACd,qBAAkB,OAAO;;EAE3B,eAAe;AACb,qBAAkB,OAAO;;EAE5B,CAAC,GACF,cAE8C,EAClD,kBAAkB,mBAAmB,QACtC,CAAC;;;;;;AAOJ,SAAS,sBACP,cACA,SAGuB;CAGvB,MAAM,gBAAuC,EAC3C,0BAA0B,cAC3B;CAKD,MAAM,OAAO,SAAS,yBAAgC;AACpD,QAAM,IAAI,MACR,wHAED;;AAGD,MAAa,2BAA2B;AAG1C,KAAI,SAAS,iBACT,MAAa,0BAA0B,QAAQ;AAGnD,QAAO;;;;;;AAsBT,SAAS,gBAA2C,SAEpB;CAC9B,MAAM,wBAAQ,IAAI,KAAuD;AAuBzE,QAAO,EACL,OAtBY,IAAI,MAAM,EAAE,EAAgC,EACxD,IAAI,SAAS,MAAM;AACjB,MAAI,SAAS,UAAU,OAAO,SAAS,SAAU,QAAO,KAAA;AAExD,MAAI,SAAS,YAAY;AACvB,YAAS,aAAa,YAAY,EAAE,CAAC;AACrC,UAAO,cAAc,YAAY;IAAE,MAAM;IAAY,MAAM,EAAE;IAAE,CAAC;;EAGlE,IAAI,KAAK,MAAM,IAAI,KAAK;AACxB,MAAI,CAAC,IAAI;AACP,SAAM,GAAG,SAAqB;AAC5B,aAAS,aAAa,MAAM,KAAK;AACjC,WAAO,cAAc,YAAY;KAAE,MAAM;KAAM;KAAM,CAAC;;AAExD,SAAM,IAAI,MAAM,GAAG;;AAErB,SAAO;IAEV,CAAC,EAID;;AAGH,SAAS,8BAIP;CACA,IAAI,SAAS;CACb,MAAM,QAAkB,EAAE;CAC1B,IAAI,aAAwD;CAE5D,MAAM,SAAS,IAAI,eAAkB;EACnC,MAAM,MAAM;AACV,gBAAa;AACb,QAAK,MAAM,SAAS,MAClB,KAAI;AACF,SAAK,QAAQ,MAAM;WACb;AAIV,SAAM,SAAS;AACf,OAAI,OACF,KAAI;AACF,SAAK,OAAO;WACN;;EAKZ,SAAS;AACP,YAAS;AACT,gBAAa;AACb,SAAM,SAAS;;EAElB,CAAC;CAEF,MAAM,QAAQ,UAAa;AACzB,MAAI,OAAQ;AACZ,MAAI,CAAC,YAAY;AACf,SAAM,KAAK,MAAM;AACjB;;AAEF,MAAI;AACF,cAAW,QAAQ,MAAM;UACnB;;CAKV,MAAM,cAAc;AAClB,MAAI,OAAQ;AACZ,WAAS;AACT,MAAI,YAAY;AACd,OAAI;AACF,eAAW,OAAO;WACZ;AAGR,gBAAa;;;AAIjB,QAAO;EAAE;EAAQ;EAAM;EAAO;;AAGhC,SAAS,mBACP,QACA,UAKmB;CACnB,MAAM,SAAS,OAAO,WAAW;CACjC,IAAI,WAAW;CAEf,MAAM,eAAe;AACnB,MAAI,SAAU;AACd,aAAW;AACX,WAAS,UAAU;AACnB,MAAI;AACF,UAAO,aAAa;UACd;;AAKV,QAAO,IAAI,eAAkB;EAC3B,MAAM,KAAK,YAAY;AACrB,OAAI;IACF,MAAM,EAAE,OAAO,SAAS,MAAM,OAAO,MAAM;AAC3C,QAAI,MAAM;AACR,gBAAW,OAAO;AAClB,aAAQ;AACR;;AAEF,eAAW,QAAQ,MAAM;YAClB,KAAK;AACZ,QAAI;AACF,gBAAW,MAAM,IAAI;YACf;AAGR,aAAS,WAAW;AACpB,YAAQ;;;EAGZ,MAAM,OAAO,QAAQ;AACnB,YAAS,YAAY;AACrB,OAAI;AACF,UAAM,OAAO,OAAO,OAAO;WACrB;AAGR,WAAQ;;EAEX,CAAC"}
+{"version":3,"file":"createCompositeComponent.js","names":[],"sources":["../../src/createCompositeComponent.ts"],"sourcesContent":["import { createElement } from 'react'\nimport { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'\nimport { getRequest } from '@tanstack/start-server-core'\nimport { getStartContext } from '@tanstack/start-storage-context'\nimport { sanitizeSlotArgs } from './slotUsageSanitizer'\nimport { ReplayableStream } from './ReplayableStream'\nimport { ClientSlot } from './ClientSlot'\nimport {\n  RSC_SLOT_USAGES_STREAM,\n  SERVER_COMPONENT_STREAM,\n} from './ServerComponentTypes'\nimport { createRscCssEnvelope } from './rscCssEnvelope'\nimport type {\n  AnyCompositeComponent,\n  CompositeComponentResult,\n  RscSlotUsageEvent,\n  ServerComponentStream,\n  ValidateCompositeComponent,\n} from './ServerComponentTypes'\nimport type { RscCssEnvelopeOptions } from './rscCssEnvelope'\n\nimport './rscSsrHandler' // Import for global declaration side effect\n\n/**\n * Creates a composite server component with slot support.\n *\n * Supports returning:\n * - A ReactNode directly\n * - An object structure with ReactNodes: accessed as `src.Foo`\n * - Nested structures: accessed as `src.x.Bar`\n *\n * Props that are functions become slots - they render as ClientSlot placeholders\n * in the RSC output, filled in by the consumer with actual implementations.\n *\n * The returned value is NOT directly renderable. Use `<CompositeComponent src={...} />`.\n *\n * @example\n * ```tsx\n * const src = await createCompositeComponent((props) => (\n *   <div>\n *     <header>{props.header('Dashboard')}</header>\n *     <main>{props.children}</main>\n *   </div>\n * ))\n *\n * // In route component\n * return (\n *   <CompositeComponent src={src} header={(title) => <h1>{title}</h1>}>\n *     <p>Main content</p>\n *   </CompositeComponent>\n * )\n * ```\n */\nexport async function createCompositeComponent<TComp>(\n  component: ValidateCompositeComponent<TComp>,\n  options?: RscCssEnvelopeOptions,\n): Promise<CompositeComponentResult<TComp>> {\n  const isDev = process.env.NODE_ENV === 'development'\n\n  // Dev-only: stream slot usage events (slot + raw args)\n  const slotUsagesEmitter = isDev\n    ? createReadableStreamEmitter<RscSlotUsageEvent>()\n    : null\n\n  // Create a wrapper component that will be rendered inside React's Flight context.\n  // This ensures React.cache works properly since the component is called during\n  // renderToReadableStream's render phase, not before it.\n  const { proxy: proxyProps } = createSlotProxy<{}>({\n    onSlotCall: slotUsagesEmitter\n      ? (name, args) => {\n          const sanitizedArgs = sanitizeSlotArgs(args)\n          slotUsagesEmitter.emit({\n            slot: name,\n            args: sanitizedArgs.length ? sanitizedArgs : undefined,\n          })\n        }\n      : undefined,\n  })\n\n  // Wrapper that renders the user's component inside Flight render context\n  async function ServerComponentWrapper() {\n    return createRscCssEnvelope(\n      await (component as React.FC)(proxyProps),\n      options,\n    )\n  }\n\n  // Render using createElement so React calls our component during Flight rendering\n  // This is critical for React.cache to work - the component must be invoked\n  // during renderToReadableStream's execution, not before\n  const flightStream = renderToReadableStream(\n    createElement(ServerComponentWrapper as any),\n  )\n\n  // Check if this is an SSR request (router) or a direct server function call\n  const ctx = getStartContext({ throwIfNotFound: false })\n  const isRouterRequest = ctx?.handlerType === 'router'\n  const ssrHandler = globalThis.__RSC_SSR__\n\n  // SSR path: buffer stream for replay, pre-decode for synchronous rendering\n  if (isRouterRequest && ssrHandler) {\n    const signal = getRequest().signal\n    const stream = new ReplayableStream(flightStream, { signal })\n\n    // Pre-decode during loader phase for synchronous SSR rendering\n    const decoded = await ssrHandler.decode(stream)\n\n    // For SSR we know decode fully consumed the Flight stream.\n    slotUsagesEmitter?.close()\n\n    return ssrHandler.createCompositeProxy(\n      stream,\n      decoded,\n      slotUsagesEmitter?.stream,\n    ) as CompositeComponentResult<TComp>\n  }\n\n  // Server function call path:\n  // The serialization adapter will stream to the client.\n  const monitoredFlightStream =\n    isDev && slotUsagesEmitter\n      ? wrapReadableStream(flightStream, {\n          onDone: () => {\n            slotUsagesEmitter.close()\n          },\n          onCancel: () => {\n            slotUsagesEmitter.close()\n          },\n          onError: () => {\n            slotUsagesEmitter.close()\n          },\n        })\n      : flightStream\n\n  return createCompositeHandle(monitoredFlightStream, {\n    slotUsagesStream: slotUsagesEmitter?.stream,\n  }) as CompositeComponentResult<TComp>\n}\n\n/**\n * Creates a composite handle for server function responses.\n * No proxy needed - the client will decode and create its own proxy.\n */\nfunction createCompositeHandle(\n  flightStream: ReadableStream<Uint8Array>,\n  options?: {\n    slotUsagesStream?: ReadableStream<RscSlotUsageEvent>\n  },\n): AnyCompositeComponent {\n  // Simple single-use stream wrapper. For server function calls, the stream\n  // is consumed exactly once by the serialization adapter for transport.\n  const streamWrapper: ServerComponentStream = {\n    createReplayStream: () => flightStream,\n  }\n\n  // Create a stub function with the stream attached for serialization.\n  // This will never be rendered directly - it goes through serialization\n  // which extracts the stream and sends it to the client.\n  const stub = function CompositeComponentStub(): never {\n    throw new Error(\n      'CompositeComponent from server function cannot be rendered on server. ' +\n        'It should be serialized and sent to the client.',\n    )\n  }\n\n  ;(stub as any)[SERVER_COMPONENT_STREAM] = streamWrapper\n  // Note: RENDERABLE_RSC is not set (or implicitly false), indicating this is a composite component\n\n  if (options?.slotUsagesStream) {\n    ;(stub as any)[RSC_SLOT_USAGES_STREAM] = options.slotUsagesStream\n  }\n\n  return stub as unknown as AnyCompositeComponent\n}\n\n/**\n * Base slot props type - functions that become ClientSlot placeholders\n */\ninterface SlotPropsBase {\n  [key: string]:\n    | ((...args: Array<any>) => React.ReactNode)\n    | React.ReactNode\n    | undefined\n  children?: React.ReactNode\n}\n\ninterface SlotProxyResult<TSlotProps extends object> {\n  proxy: TSlotProps & SlotPropsBase\n}\n\n/**\n * Proxy that turns property access into ClientSlot renders.\n * Also tracks accessed slot names for devtools.\n */\nfunction createSlotProxy<TSlotProps extends object>(options?: {\n  onSlotCall?: (name: string, args: Array<any>) => void\n}): SlotProxyResult<TSlotProps> {\n  const cache = new Map<string, (...args: Array<any>) => React.ReactNode>()\n\n  const proxy = new Proxy({} as TSlotProps & SlotPropsBase, {\n    get(_target, prop) {\n      if (prop === 'then' || typeof prop !== 'string') return undefined\n\n      if (prop === 'children') {\n        options?.onSlotCall?.('children', [])\n        return createElement(ClientSlot, { slot: 'children', args: [] })\n      }\n\n      let fn = cache.get(prop)\n      if (!fn) {\n        fn = (...args: Array<any>) => {\n          options?.onSlotCall?.(prop, args)\n          return createElement(ClientSlot, { slot: prop, args })\n        }\n        cache.set(prop, fn)\n      }\n      return fn\n    },\n  })\n\n  return {\n    proxy,\n  }\n}\n\nfunction createReadableStreamEmitter<T>(): {\n  stream: ReadableStream<T>\n  emit: (value: T) => void\n  close: () => void\n} {\n  let closed = false\n  const queue: Array<T> = []\n  let controller: ReadableStreamDefaultController<T> | null = null\n\n  const stream = new ReadableStream<T>({\n    start(ctrl) {\n      controller = ctrl\n      for (const value of queue) {\n        try {\n          ctrl.enqueue(value)\n        } catch {\n          // Ignore\n        }\n      }\n      queue.length = 0\n      if (closed) {\n        try {\n          ctrl.close()\n        } catch {\n          // Ignore\n        }\n      }\n    },\n    cancel() {\n      closed = true\n      controller = null\n      queue.length = 0\n    },\n  })\n\n  const emit = (value: T) => {\n    if (closed) return\n    if (!controller) {\n      queue.push(value)\n      return\n    }\n    try {\n      controller.enqueue(value)\n    } catch {\n      // Ignore\n    }\n  }\n\n  const close = () => {\n    if (closed) return\n    closed = true\n    if (controller) {\n      try {\n        controller.close()\n      } catch {\n        // Ignore\n      }\n      controller = null\n    }\n  }\n\n  return { stream, emit, close }\n}\n\nfunction wrapReadableStream<T>(\n  source: ReadableStream<T>,\n  handlers: {\n    onDone?: () => void\n    onCancel?: () => void\n    onError?: () => void\n  },\n): ReadableStream<T> {\n  const reader = source.getReader()\n  let finished = false\n\n  const finish = () => {\n    if (finished) return\n    finished = true\n    handlers.onDone?.()\n    try {\n      reader.releaseLock()\n    } catch {\n      // Ignore\n    }\n  }\n\n  return new ReadableStream<T>({\n    async pull(controller) {\n      try {\n        const { value, done } = await reader.read()\n        if (done) {\n          controller.close()\n          finish()\n          return\n        }\n        controller.enqueue(value)\n      } catch (err) {\n        try {\n          controller.error(err)\n        } catch {\n          // Ignore\n        }\n        handlers.onError?.()\n        finish()\n      }\n    },\n    async cancel(reason) {\n      handlers.onCancel?.()\n      try {\n        await reader.cancel(reason)\n      } catch {\n        // Ignore\n      }\n      finish()\n    },\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,eAAsB,yBACpB,WACA,SAC0C;CAC1C,MAAM,QAAA,QAAA,IAAA,aAAiC;CAGvC,MAAM,oBAAoB,QACtB,6BAAgD,GAChD;CAKJ,MAAM,EAAE,OAAO,eAAe,gBAAoB,EAChD,YAAY,qBACP,MAAM,SAAS;EACd,MAAM,gBAAgB,iBAAiB,KAAK;AAC5C,oBAAkB,KAAK;GACrB,MAAM;GACN,MAAM,cAAc,SAAS,gBAAgB,KAAA;GAC9C,CAAC;KAEJ,KAAA,GACL,CAAC;CAGF,eAAe,yBAAyB;AACtC,SAAO,qBACL,MAAO,UAAuB,WAAW,EACzC,QACD;;CAMH,MAAM,eAAe,uBACnB,cAAc,uBAA8B,CAC7C;CAID,MAAM,kBADM,gBAAgB,EAAE,iBAAiB,OAAO,CAAC,EAC1B,gBAAgB;CAC7C,MAAM,aAAa,WAAW;AAG9B,KAAI,mBAAmB,YAAY;EACjC,MAAM,SAAS,YAAY,CAAC;EAC5B,MAAM,SAAS,IAAI,iBAAiB,cAAc,EAAE,QAAQ,CAAC;EAG7D,MAAM,UAAU,MAAM,WAAW,OAAO,OAAO;AAG/C,qBAAmB,OAAO;AAE1B,SAAO,WAAW,qBAChB,QACA,SACA,mBAAmB,OACpB;;AAoBH,QAAO,sBAdL,SAAS,oBACL,mBAAmB,cAAc;EAC/B,cAAc;AACZ,qBAAkB,OAAO;;EAE3B,gBAAgB;AACd,qBAAkB,OAAO;;EAE3B,eAAe;AACb,qBAAkB,OAAO;;EAE5B,CAAC,GACF,cAE8C,EAClD,kBAAkB,mBAAmB,QACtC,CAAC;;;;;;AAOJ,SAAS,sBACP,cACA,SAGuB;CAGvB,MAAM,gBAAuC,EAC3C,0BAA0B,cAC3B;CAKD,MAAM,OAAO,SAAS,yBAAgC;AACpD,QAAM,IAAI,MACR,wHAED;;AAGD,MAAa,2BAA2B;AAG1C,KAAI,SAAS,iBACT,MAAa,0BAA0B,QAAQ;AAGnD,QAAO;;;;;;AAsBT,SAAS,gBAA2C,SAEpB;CAC9B,MAAM,wBAAQ,IAAI,KAAuD;AAuBzE,QAAO,EACL,OAtBY,IAAI,MAAM,EAAE,EAAgC,EACxD,IAAI,SAAS,MAAM;AACjB,MAAI,SAAS,UAAU,OAAO,SAAS,SAAU,QAAO,KAAA;AAExD,MAAI,SAAS,YAAY;AACvB,YAAS,aAAa,YAAY,EAAE,CAAC;AACrC,UAAO,cAAc,YAAY;IAAE,MAAM;IAAY,MAAM,EAAE;IAAE,CAAC;;EAGlE,IAAI,KAAK,MAAM,IAAI,KAAK;AACxB,MAAI,CAAC,IAAI;AACP,SAAM,GAAG,SAAqB;AAC5B,aAAS,aAAa,MAAM,KAAK;AACjC,WAAO,cAAc,YAAY;KAAE,MAAM;KAAM;KAAM,CAAC;;AAExD,SAAM,IAAI,MAAM,GAAG;;AAErB,SAAO;IAEV,CAAC,EAID;;AAGH,SAAS,8BAIP;CACA,IAAI,SAAS;CACb,MAAM,QAAkB,EAAE;CAC1B,IAAI,aAAwD;CAE5D,MAAM,SAAS,IAAI,eAAkB;EACnC,MAAM,MAAM;AACV,gBAAa;AACb,QAAK,MAAM,SAAS,MAClB,KAAI;AACF,SAAK,QAAQ,MAAM;WACb;AAIV,SAAM,SAAS;AACf,OAAI,OACF,KAAI;AACF,SAAK,OAAO;WACN;;EAKZ,SAAS;AACP,YAAS;AACT,gBAAa;AACb,SAAM,SAAS;;EAElB,CAAC;CAEF,MAAM,QAAQ,UAAa;AACzB,MAAI,OAAQ;AACZ,MAAI,CAAC,YAAY;AACf,SAAM,KAAK,MAAM;AACjB;;AAEF,MAAI;AACF,cAAW,QAAQ,MAAM;UACnB;;CAKV,MAAM,cAAc;AAClB,MAAI,OAAQ;AACZ,WAAS;AACT,MAAI,YAAY;AACd,OAAI;AACF,eAAW,OAAO;WACZ;AAGR,gBAAa;;;AAIjB,QAAO;EAAE;EAAQ;EAAM;EAAO;;AAGhC,SAAS,mBACP,QACA,UAKmB;CACnB,MAAM,SAAS,OAAO,WAAW;CACjC,IAAI,WAAW;CAEf,MAAM,eAAe;AACnB,MAAI,SAAU;AACd,aAAW;AACX,WAAS,UAAU;AACnB,MAAI;AACF,UAAO,aAAa;UACd;;AAKV,QAAO,IAAI,eAAkB;EAC3B,MAAM,KAAK,YAAY;AACrB,OAAI;IACF,MAAM,EAAE,OAAO,SAAS,MAAM,OAAO,MAAM;AAC3C,QAAI,MAAM;AACR,gBAAW,OAAO;AAClB,aAAQ;AACR;;AAEF,eAAW,QAAQ,MAAM;YAClB,KAAK;AACZ,QAAI;AACF,gBAAW,MAAM,IAAI;YACf;AAGR,aAAS,WAAW;AACpB,YAAQ;;;EAGZ,MAAM,OAAO,QAAQ;AACnB,YAAS,YAAY;AACrB,OAAI;AACF,UAAM,OAAO,OAAO,OAAO;WACrB;AAGR,WAAQ;;EAEX,CAAC"}

package/dist/esm/createServerComponentFromStream.js

@@ -1,4 +1,5 @@
 "use client";
+import { unwrapRscCssEnvelope } from "./rscCssEnvelope.js";
 import { awaitLazyElements } from "./awaitLazyElements.js";
 import { createRscProxy } from "./createRscProxy.js";
 import { use } from "react";
@@ -52,9 +53,9 @@ function setupStreamDecode(stream) {
 		await awaitLazyElements(result, (href) => {
 			cssHrefs.add(href);
 		});
-		cachedTree = result;
+		cachedTree = unwrapRscCssEnvelope(result);
 		cacheReady = true;
-		return result;
+		return cachedTree;
 	});
 	trackPostProcessPromise(transformedTreePromise);
 	const streamWrapper = { createReplayStream: () => stream };

package/dist/esm/createServerComponentFromStream.js.map

@@ -1 +1 @@
-{"version":3,"file":"createServerComponentFromStream.js","names":[],"sources":["../../src/createServerComponentFromStream.ts"],"sourcesContent":["'use client'\n\nimport { use } from 'react'\nimport { trackPostProcessPromise } from '@tanstack/start-client-core'\nimport { createFromReadableStream as browserDecode } from 'virtual:tanstack-rsc-browser-decode'\n\nimport { awaitLazyElements } from './awaitLazyElements'\nimport { createRscProxy } from './createRscProxy'\nimport type {\n  AnyCompositeComponent,\n  RscSlotUsageEvent,\n  ServerComponentStream,\n} from './ServerComponentTypes'\n\n/**\n * Creates a renderable RSC proxy from a raw Flight stream.\n * Client-side only - used by the client serialization adapter for `renderServerComponent`.\n *\n * Returns a Proxy that:\n * - Can be rendered directly as `{data}` in JSX\n * - Supports nested access: `{data.foo.bar}`\n * - Masquerades as a React element\n */\nexport function createRenderableFromStream(\n  stream: ReadableStream<Uint8Array>,\n): any {\n  const { getTree, streamWrapper, cssHrefs } = setupStreamDecode(stream)\n\n  return createRscProxy(getTree, {\n    stream: streamWrapper,\n    cssHrefs,\n    renderable: true,\n  })\n}\n\n/**\n * Creates a composite RSC proxy from a raw Flight stream.\n * Client-side only - used by the client serialization adapter for `createCompositeComponent`.\n *\n * Returns a Proxy that:\n * - NOT directly renderable\n * - Supports nested access: `src.foo.bar`\n * - Must be rendered via `<CompositeComponent src={...} />`\n */\nexport function createCompositeFromStream(\n  stream: ReadableStream<Uint8Array>,\n  options?: {\n    slotUsagesStream?: ReadableStream<RscSlotUsageEvent>\n  },\n): AnyCompositeComponent {\n  const { getTree, streamWrapper, cssHrefs } = setupStreamDecode(stream)\n\n  return createRscProxy(getTree, {\n    stream: streamWrapper,\n    cssHrefs,\n    renderable: false,\n    slotUsagesStream: options?.slotUsagesStream,\n  })\n}\n\n/**\n * Shared stream decode setup for both renderable and composite.\n */\nfunction setupStreamDecode(stream: ReadableStream<Uint8Array>): {\n  getTree: () => unknown\n  streamWrapper: ServerComponentStream\n  cssHrefs: Set<string> | undefined\n} {\n  // Start decoding eagerly during deserialization\n  const decodeThenable = browserDecode(stream)\n  const cssHrefs = new Set<string>()\n\n  // Synchronous cache for the decoded tree.\n  let cachedTree: unknown = undefined\n  let cacheReady = false\n\n  // Promise for the tree with lazy elements awaited.\n  const transformedTreePromise = Promise.resolve(decodeThenable).then(\n    async (result) => {\n      await awaitLazyElements(result, (href) => {\n        cssHrefs.add(href)\n      })\n      cachedTree = result\n      cacheReady = true\n      return result\n    },\n  )\n\n  // Track the lazy element loading - prevents flash\n  trackPostProcessPromise(transformedTreePromise)\n\n  const streamWrapper: ServerComponentStream = {\n    createReplayStream: () => stream,\n  }\n\n  const getTree = () => {\n    if (cacheReady) return cachedTree\n    // eslint-disable-next-line react-hooks/rules-of-hooks\n    return use(transformedTreePromise)\n  }\n\n  return { getTree, streamWrapper, cssHrefs }\n}\n// Legacy export for backwards compatibility during migration\nexport const createServerComponentFromStream = createCompositeFromStream\n"],"mappings":";;;;;;;;;;;;;;;;AAuBA,SAAgB,2BACd,QACK;CACL,MAAM,EAAE,SAAS,eAAe,aAAa,kBAAkB,OAAO;AAEtE,QAAO,eAAe,SAAS;EAC7B,QAAQ;EACR;EACA,YAAY;EACb,CAAC;;;;;;;;;;;AAYJ,SAAgB,0BACd,QACA,SAGuB;CACvB,MAAM,EAAE,SAAS,eAAe,aAAa,kBAAkB,OAAO;AAEtE,QAAO,eAAe,SAAS;EAC7B,QAAQ;EACR;EACA,YAAY;EACZ,kBAAkB,SAAS;EAC5B,CAAC;;;;;AAMJ,SAAS,kBAAkB,QAIzB;CAEA,MAAM,iBAAiB,yBAAc,OAAO;CAC5C,MAAM,2BAAW,IAAI,KAAa;CAGlC,IAAI,aAAsB,KAAA;CAC1B,IAAI,aAAa;CAGjB,MAAM,yBAAyB,QAAQ,QAAQ,eAAe,CAAC,KAC7D,OAAO,WAAW;AAChB,QAAM,kBAAkB,SAAS,SAAS;AACxC,YAAS,IAAI,KAAK;IAClB;AACF,eAAa;AACb,eAAa;AACb,SAAO;GAEV;AAGD,yBAAwB,uBAAuB;CAE/C,MAAM,gBAAuC,EAC3C,0BAA0B,QAC3B;CAED,MAAM,gBAAgB;AACpB,MAAI,WAAY,QAAO;AAEvB,SAAO,IAAI,uBAAuB;;AAGpC,QAAO;EAAE;EAAS;EAAe;EAAU"}
+{"version":3,"file":"createServerComponentFromStream.js","names":[],"sources":["../../src/createServerComponentFromStream.ts"],"sourcesContent":["'use client'\n\nimport { use } from 'react'\nimport { trackPostProcessPromise } from '@tanstack/start-client-core'\nimport { createFromReadableStream as browserDecode } from 'virtual:tanstack-rsc-browser-decode'\n\nimport { awaitLazyElements } from './awaitLazyElements'\nimport { createRscProxy } from './createRscProxy'\nimport { unwrapRscCssEnvelope } from './rscCssEnvelope'\nimport type {\n  AnyCompositeComponent,\n  RscSlotUsageEvent,\n  ServerComponentStream,\n} from './ServerComponentTypes'\n\n/**\n * Creates a renderable RSC proxy from a raw Flight stream.\n * Client-side only - used by the client serialization adapter for `renderServerComponent`.\n *\n * Returns a Proxy that:\n * - Can be rendered directly as `{data}` in JSX\n * - Supports nested access: `{data.foo.bar}`\n * - Masquerades as a React element\n */\nexport function createRenderableFromStream(\n  stream: ReadableStream<Uint8Array>,\n): any {\n  const { getTree, streamWrapper, cssHrefs } = setupStreamDecode(stream)\n\n  return createRscProxy(getTree, {\n    stream: streamWrapper,\n    cssHrefs,\n    renderable: true,\n  })\n}\n\n/**\n * Creates a composite RSC proxy from a raw Flight stream.\n * Client-side only - used by the client serialization adapter for `createCompositeComponent`.\n *\n * Returns a Proxy that:\n * - NOT directly renderable\n * - Supports nested access: `src.foo.bar`\n * - Must be rendered via `<CompositeComponent src={...} />`\n */\nexport function createCompositeFromStream(\n  stream: ReadableStream<Uint8Array>,\n  options?: {\n    slotUsagesStream?: ReadableStream<RscSlotUsageEvent>\n  },\n): AnyCompositeComponent {\n  const { getTree, streamWrapper, cssHrefs } = setupStreamDecode(stream)\n\n  return createRscProxy(getTree, {\n    stream: streamWrapper,\n    cssHrefs,\n    renderable: false,\n    slotUsagesStream: options?.slotUsagesStream,\n  })\n}\n\n/**\n * Shared stream decode setup for both renderable and composite.\n */\nfunction setupStreamDecode(stream: ReadableStream<Uint8Array>): {\n  getTree: () => unknown\n  streamWrapper: ServerComponentStream\n  cssHrefs: Set<string> | undefined\n} {\n  // Start decoding eagerly during deserialization\n  const decodeThenable = browserDecode(stream)\n  const cssHrefs = new Set<string>()\n\n  // Synchronous cache for the decoded tree.\n  let cachedTree: unknown = undefined\n  let cacheReady = false\n\n  // Promise for the tree with lazy elements awaited.\n  const transformedTreePromise = Promise.resolve(decodeThenable).then(\n    async (result) => {\n      await awaitLazyElements(result, (href) => {\n        cssHrefs.add(href)\n      })\n      cachedTree = unwrapRscCssEnvelope(result)\n      cacheReady = true\n      return cachedTree\n    },\n  )\n\n  // Track the lazy element loading - prevents flash\n  trackPostProcessPromise(transformedTreePromise)\n\n  const streamWrapper: ServerComponentStream = {\n    createReplayStream: () => stream,\n  }\n\n  const getTree = () => {\n    if (cacheReady) return cachedTree\n    // eslint-disable-next-line react-hooks/rules-of-hooks\n    return use(transformedTreePromise)\n  }\n\n  return { getTree, streamWrapper, cssHrefs }\n}\n// Legacy export for backwards compatibility during migration\nexport const createServerComponentFromStream = createCompositeFromStream\n"],"mappings":";;;;;;;;;;;;;;;;;AAwBA,SAAgB,2BACd,QACK;CACL,MAAM,EAAE,SAAS,eAAe,aAAa,kBAAkB,OAAO;AAEtE,QAAO,eAAe,SAAS;EAC7B,QAAQ;EACR;EACA,YAAY;EACb,CAAC;;;;;;;;;;;AAYJ,SAAgB,0BACd,QACA,SAGuB;CACvB,MAAM,EAAE,SAAS,eAAe,aAAa,kBAAkB,OAAO;AAEtE,QAAO,eAAe,SAAS;EAC7B,QAAQ;EACR;EACA,YAAY;EACZ,kBAAkB,SAAS;EAC5B,CAAC;;;;;AAMJ,SAAS,kBAAkB,QAIzB;CAEA,MAAM,iBAAiB,yBAAc,OAAO;CAC5C,MAAM,2BAAW,IAAI,KAAa;CAGlC,IAAI,aAAsB,KAAA;CAC1B,IAAI,aAAa;CAGjB,MAAM,yBAAyB,QAAQ,QAAQ,eAAe,CAAC,KAC7D,OAAO,WAAW;AAChB,QAAM,kBAAkB,SAAS,SAAS;AACxC,YAAS,IAAI,KAAK;IAClB;AACF,eAAa,qBAAqB,OAAO;AACzC,eAAa;AACb,SAAO;GAEV;AAGD,yBAAwB,uBAAuB;CAE/C,MAAM,gBAAuC,EAC3C,0BAA0B,QAC3B;CAED,MAAM,gBAAgB;AACpB,MAAI,WAAY,QAAO;AAEvB,SAAO,IAAI,uBAAuB;;AAGpC,QAAO;EAAE;EAAS;EAAe;EAAU"}

package/dist/esm/plugin/rscCssTransform.js

@@ -0,0 +1,79 @@
+//#region src/plugin/rscCssTransform.ts
+var TSS_SERVERFN_SPLIT_PARAM = "tss-serverfn-split";
+var RSC_CSS_OPTIONS_KEY = "__tanstackStartRscCss";
+function createRscCssCompilerTransforms(opts) {
+	let loadCssExpression;
+	const getLoadCssExpression = (context) => {
+		loadCssExpression ??= context.parseExpression(opts.loadCssExpression);
+		return loadCssExpression;
+	};
+	return [
+		createRscCssCompilerTransform({
+			serverFnProviderOnly: opts.serverFnProviderOnly,
+			getLoadCssExpression,
+			kind: "renderServerComponent",
+			name: "react-rsc-render-server-component-css"
+		}),
+		createRscCssCompilerTransform({
+			serverFnProviderOnly: opts.serverFnProviderOnly,
+			getLoadCssExpression,
+			kind: "createCompositeComponent",
+			name: "react-rsc-create-composite-component-css"
+		}),
+		createRscCssCompilerTransform({
+			serverFnProviderOnly: opts.serverFnProviderOnly,
+			getLoadCssExpression,
+			kind: "renderToReadableStream",
+			name: "react-rsc-render-to-readable-stream-css"
+		})
+	];
+}
+function createRscCssCompilerTransform(opts) {
+	return {
+		name: opts.name,
+		environment: "server",
+		imports: [{
+			libName: "@tanstack/react-start/rsc",
+			rootExport: opts.kind
+		}, {
+			libName: "@tanstack/react-start-rsc",
+			rootExport: opts.kind
+		}],
+		detect: new RegExp(`\\b${opts.kind}\\b`),
+		transform: (candidates, context) => {
+			if (opts.serverFnProviderOnly && !context.id.includes(TSS_SERVERFN_SPLIT_PARAM)) return;
+			const t = context.types;
+			const loadCssExpression = opts.getLoadCssExpression(context);
+			const cloneLoadCssExpression = () => t.cloneNode(loadCssExpression);
+			for (const candidate of candidates) {
+				const args = candidate.path.node.arguments;
+				if (args.length !== 1) continue;
+				if (opts.kind === "renderToReadableStream") {
+					const firstArg = args[0];
+					if (!firstArg || !t.isExpression(firstArg)) continue;
+					if (!isTopLevelJsx(t, firstArg)) continue;
+					args[0] = createCssFragment(t, firstArg, cloneLoadCssExpression());
+					continue;
+				}
+				args.push(t.objectExpression([t.objectProperty(t.identifier(RSC_CSS_OPTIONS_KEY), cloneLoadCssExpression())]));
+			}
+		}
+	};
+}
+function isTopLevelJsx(t, expr) {
+	const unwrapped = unwrapTransparentExpression(t, expr);
+	return t.isJSXElement(unwrapped) || t.isJSXFragment(unwrapped);
+}
+function unwrapTransparentExpression(t, expr) {
+	let current = expr;
+	while (t.isParenthesizedExpression(current) || t.isTSAsExpression(current) || t.isTSSatisfiesExpression(current) || t.isTSTypeAssertion(current) || t.isTSNonNullExpression(current)) current = current.expression;
+	return current;
+}
+function createCssFragment(t, original, loadCssExpression) {
+	const unwrapped = unwrapTransparentExpression(t, original);
+	return t.jsxFragment(t.jsxOpeningFragment(), t.jsxClosingFragment(), [t.jsxExpressionContainer(loadCssExpression), t.isJSXElement(unwrapped) || t.isJSXFragment(unwrapped) ? unwrapped : t.jsxExpressionContainer(original)]);
+}
+//#endregion
+export { createRscCssCompilerTransforms };
+
+//# sourceMappingURL=rscCssTransform.js.map

package/dist/esm/plugin/rscCssTransform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rscCssTransform.js","names":[],"sources":["../../../src/plugin/rscCssTransform.ts"],"sourcesContent":["import type {\n  StartCompilerImportTransform,\n  StartCompilerTransformContext,\n} from '@tanstack/start-plugin-core'\n\nconst TSS_SERVERFN_SPLIT_PARAM = 'tss-serverfn-split'\nconst RSC_CSS_OPTIONS_KEY = '__tanstackStartRscCss'\n\ntype BabelTypes = StartCompilerTransformContext['types']\ntype BabelExpression = ReturnType<\n  StartCompilerTransformContext['parseExpression']\n>\n\ntype RscCssTransformKind =\n  | 'renderServerComponent'\n  | 'createCompositeComponent'\n  | 'renderToReadableStream'\n\nexport function createRscCssCompilerTransforms(opts: {\n  loadCssExpression: string\n  serverFnProviderOnly?: boolean | undefined\n}): Array<StartCompilerImportTransform> {\n  let loadCssExpression: BabelExpression | undefined\n\n  const getLoadCssExpression = (context: StartCompilerTransformContext) => {\n    loadCssExpression ??= context.parseExpression(opts.loadCssExpression)\n    return loadCssExpression\n  }\n\n  return [\n    createRscCssCompilerTransform({\n      serverFnProviderOnly: opts.serverFnProviderOnly,\n      getLoadCssExpression,\n      kind: 'renderServerComponent',\n      name: 'react-rsc-render-server-component-css',\n    }),\n    createRscCssCompilerTransform({\n      serverFnProviderOnly: opts.serverFnProviderOnly,\n      getLoadCssExpression,\n      kind: 'createCompositeComponent',\n      name: 'react-rsc-create-composite-component-css',\n    }),\n    createRscCssCompilerTransform({\n      serverFnProviderOnly: opts.serverFnProviderOnly,\n      getLoadCssExpression,\n      kind: 'renderToReadableStream',\n      name: 'react-rsc-render-to-readable-stream-css',\n    }),\n  ]\n}\n\nfunction createRscCssCompilerTransform(opts: {\n  name: string\n  kind: RscCssTransformKind\n  getLoadCssExpression: (\n    context: StartCompilerTransformContext,\n  ) => BabelExpression\n  serverFnProviderOnly?: boolean | undefined\n}): StartCompilerImportTransform {\n  return {\n    name: opts.name,\n    environment: 'server',\n    imports: [\n      {\n        libName: '@tanstack/react-start/rsc',\n        rootExport: opts.kind,\n      },\n      {\n        libName: '@tanstack/react-start-rsc',\n        rootExport: opts.kind,\n      },\n    ],\n    detect: new RegExp(`\\\\b${opts.kind}\\\\b`),\n    transform: (candidates, context) => {\n      if (\n        opts.serverFnProviderOnly &&\n        !context.id.includes(TSS_SERVERFN_SPLIT_PARAM)\n      ) {\n        return\n      }\n\n      const t = context.types\n      const loadCssExpression = opts.getLoadCssExpression(context)\n      const cloneLoadCssExpression = () => t.cloneNode(loadCssExpression)\n\n      for (const candidate of candidates) {\n        const args = candidate.path.node.arguments\n        if (args.length !== 1) continue\n\n        if (opts.kind === 'renderToReadableStream') {\n          const firstArg = args[0]\n          if (!firstArg || !t.isExpression(firstArg)) continue\n          if (!isTopLevelJsx(t, firstArg)) continue\n\n          args[0] = createCssFragment(\n            t,\n            firstArg,\n            cloneLoadCssExpression(),\n          ) as typeof firstArg\n          continue\n        }\n\n        args.push(\n          t.objectExpression([\n            t.objectProperty(\n              t.identifier(RSC_CSS_OPTIONS_KEY),\n              cloneLoadCssExpression(),\n            ),\n          ]),\n        )\n      }\n    },\n  }\n}\n\nfunction isTopLevelJsx(t: BabelTypes, expr: BabelExpression): boolean {\n  const unwrapped = unwrapTransparentExpression(t, expr)\n  return t.isJSXElement(unwrapped) || t.isJSXFragment(unwrapped)\n}\n\nfunction unwrapTransparentExpression(\n  t: BabelTypes,\n  expr: BabelExpression,\n): BabelExpression {\n  let current = expr\n  while (\n    t.isParenthesizedExpression(current) ||\n    t.isTSAsExpression(current) ||\n    t.isTSSatisfiesExpression(current) ||\n    t.isTSTypeAssertion(current) ||\n    t.isTSNonNullExpression(current)\n  ) {\n    current = current.expression\n  }\n  return current\n}\n\nfunction createCssFragment(\n  t: BabelTypes,\n  original: BabelExpression,\n  loadCssExpression: BabelExpression,\n) {\n  const unwrapped = unwrapTransparentExpression(t, original)\n  return t.jsxFragment(t.jsxOpeningFragment(), t.jsxClosingFragment(), [\n    t.jsxExpressionContainer(loadCssExpression),\n    t.isJSXElement(unwrapped) || t.isJSXFragment(unwrapped)\n      ? unwrapped\n      : t.jsxExpressionContainer(original),\n  ])\n}\n"],"mappings":";AAKA,IAAM,2BAA2B;AACjC,IAAM,sBAAsB;AAY5B,SAAgB,+BAA+B,MAGP;CACtC,IAAI;CAEJ,MAAM,wBAAwB,YAA2C;AACvE,wBAAsB,QAAQ,gBAAgB,KAAK,kBAAkB;AACrE,SAAO;;AAGT,QAAO;EACL,8BAA8B;GAC5B,sBAAsB,KAAK;GAC3B;GACA,MAAM;GACN,MAAM;GACP,CAAC;EACF,8BAA8B;GAC5B,sBAAsB,KAAK;GAC3B;GACA,MAAM;GACN,MAAM;GACP,CAAC;EACF,8BAA8B;GAC5B,sBAAsB,KAAK;GAC3B;GACA,MAAM;GACN,MAAM;GACP,CAAC;EACH;;AAGH,SAAS,8BAA8B,MAON;AAC/B,QAAO;EACL,MAAM,KAAK;EACX,aAAa;EACb,SAAS,CACP;GACE,SAAS;GACT,YAAY,KAAK;GAClB,EACD;GACE,SAAS;GACT,YAAY,KAAK;GAClB,CACF;EACD,QAAQ,IAAI,OAAO,MAAM,KAAK,KAAK,KAAK;EACxC,YAAY,YAAY,YAAY;AAClC,OACE,KAAK,wBACL,CAAC,QAAQ,GAAG,SAAS,yBAAyB,CAE9C;GAGF,MAAM,IAAI,QAAQ;GAClB,MAAM,oBAAoB,KAAK,qBAAqB,QAAQ;GAC5D,MAAM,+BAA+B,EAAE,UAAU,kBAAkB;AAEnE,QAAK,MAAM,aAAa,YAAY;IAClC,MAAM,OAAO,UAAU,KAAK,KAAK;AACjC,QAAI,KAAK,WAAW,EAAG;AAEvB,QAAI,KAAK,SAAS,0BAA0B;KAC1C,MAAM,WAAW,KAAK;AACtB,SAAI,CAAC,YAAY,CAAC,EAAE,aAAa,SAAS,CAAE;AAC5C,SAAI,CAAC,cAAc,GAAG,SAAS,CAAE;AAEjC,UAAK,KAAK,kBACR,GACA,UACA,wBAAwB,CACzB;AACD;;AAGF,SAAK,KACH,EAAE,iBAAiB,CACjB,EAAE,eACA,EAAE,WAAW,oBAAoB,EACjC,wBAAwB,CACzB,CACF,CAAC,CACH;;;EAGN;;AAGH,SAAS,cAAc,GAAe,MAAgC;CACpE,MAAM,YAAY,4BAA4B,GAAG,KAAK;AACtD,QAAO,EAAE,aAAa,UAAU,IAAI,EAAE,cAAc,UAAU;;AAGhE,SAAS,4BACP,GACA,MACiB;CACjB,IAAI,UAAU;AACd,QACE,EAAE,0BAA0B,QAAQ,IACpC,EAAE,iBAAiB,QAAQ,IAC3B,EAAE,wBAAwB,QAAQ,IAClC,EAAE,kBAAkB,QAAQ,IAC5B,EAAE,sBAAsB,QAAQ,CAEhC,WAAU,QAAQ;AAEpB,QAAO;;AAGT,SAAS,kBACP,GACA,UACA,mBACA;CACA,MAAM,YAAY,4BAA4B,GAAG,SAAS;AAC1D,QAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,EAAE,oBAAoB,EAAE,CACnE,EAAE,uBAAuB,kBAAkB,EAC3C,EAAE,aAAa,UAAU,IAAI,EAAE,cAAc,UAAU,GACnD,YACA,EAAE,uBAAuB,SAAS,CACvC,CAAC"}

package/dist/esm/plugin/vite.js

@@ -1,3 +1,4 @@
+import { createRscCssCompilerTransforms } from "./rscCssTransform.js";
 import { fileURLToPath } from "node:url";
 import path from "pathe";
 import { createVirtualModule } from "@tanstack/start-plugin-core/vite";
@@ -32,7 +33,8 @@ function configureRsc() {
 				export: "rscSerializationAdapter",
 				isFactory: true
 			}
-		}]
+		}],
+		compilerTransforms: createRscCssCompilerTransforms({ loadCssExpression: "import.meta.viteRsc.loadCss()" })
 	};
 }
 function reactStartRscVitePlugin() {
@@ -64,6 +66,21 @@ function reactStartRscVitePlugin() {
 				};
 			}
 		},
+		{
+			name: "tanstack-react-start:rsc-scan-virtual-fallback",
+			apply: "build",
+			applyToEnvironment(env) {
+				return env.name === RSC_ENV_NAME;
+			},
+			load: {
+				filter: { id: /^(virtual:tanstack-rsc-runtime|virtual:vite-rsc\/encryption-key)$/ },
+				handler(id) {
+					if (this.environment.config.build.write !== false) return;
+					if (id === RSC_RUNTIME_VIRTUAL_ID) return `export { renderToReadableStream, createFromReadableStream, createTemporaryReferenceSet, decodeReply, loadServerAction, decodeAction, decodeFormState } from '@vitejs/plugin-rsc/rsc'`;
+					if (id === "virtual:vite-rsc/encryption-key") return `export default () => ''`;
+				}
+			}
+		},
 		createVirtualModule({
 			name: "tanstack-react-start:rsc-runtime-virtual",
 			moduleId: RSC_RUNTIME_VIRTUAL_ID,

package/dist/esm/plugin/vite.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite.js","names":[],"sources":["../../../src/plugin/vite.ts"],"sourcesContent":["import { fileURLToPath } from 'node:url'\nimport path from 'pathe'\nimport { createVirtualModule } from '@tanstack/start-plugin-core/vite'\nimport type {\n  TanStackStartVitePluginCoreOptions,\n  ViteRscForwardSsrResolverStrategy,\n} from '@tanstack/start-plugin-core/vite'\nimport type { PluginOption, UserConfig } from 'vite'\n\nconst isClientEnvironment = (env: { config: { consumer: string } }) =>\n  env.config.consumer === 'client'\n\n// Virtual module ids used by the React Start RSC runtime.\nconst RSC_HMR_VIRTUAL_ID = 'virtual:tanstack-rsc-hmr'\nconst RSC_RUNTIME_VIRTUAL_ID = 'virtual:tanstack-rsc-runtime'\nconst RSC_BROWSER_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-browser-decode'\nconst RSC_SSR_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-ssr-decode'\nconst RSC_ENV_NAME = 'rsc'\n\nconst currentDir = path.dirname(fileURLToPath(import.meta.url))\nconst entryDir = path.resolve(currentDir, '..', '..', 'plugin', 'entry')\nconst rscEntryPath = path.resolve(entryDir, 'rsc.tsx')\n\nexport function configureRsc(): {\n  envName: string\n  providerEnvironmentName: TanStackStartVitePluginCoreOptions['providerEnvironmentName']\n  ssrResolverStrategy: TanStackStartVitePluginCoreOptions['ssrResolverStrategy']\n  serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters']\n} {\n  const serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters'] =\n    [\n      // IMPORTANT: plugin-adapters-plugin only calls the top-level factory once.\n      // That factory must return a flat array of adapters (not nested arrays),\n      // otherwise router-core ends up with non-adapter entries and Seroval crashes.\n      {\n        client: {\n          module: '@tanstack/react-start/rsc/serialization/client',\n          export: 'rscSerializationAdapter',\n          isFactory: true,\n        },\n        server: {\n          module: '@tanstack/react-start/rsc/serialization/server',\n          export: 'rscSerializationAdapter',\n          isFactory: true,\n        },\n      },\n    ]\n  const ssrResolverStrategy = {\n    type: 'vite-rsc-forward',\n    sourceEnvironmentName: RSC_ENV_NAME,\n    sourceEntry: 'index',\n    exportName: 'getServerFnById',\n  } satisfies ViteRscForwardSsrResolverStrategy\n  return {\n    envName: RSC_ENV_NAME,\n    providerEnvironmentName: RSC_ENV_NAME,\n    ssrResolverStrategy,\n    serializationAdapters,\n  }\n}\nexport function reactStartRscVitePlugin(): PluginOption {\n  return [\n    // When RSC is enabled, SSR needs noExternal: true to ensure single React instance.\n    // The RSC decoder's dynamic imports for client components can cause module duplication\n    // without this, leading to \"Invalid hook call\" errors.\n    // We use the top-level `ssr` config option as `environments.ssr.resolve.noExternal`\n    // doesn't have the same effect.\n    {\n      name: 'tanstack-react-start:rsc-ssr-config',\n      config() {\n        return {\n          ssr: {\n            noExternal: true,\n          },\n        }\n      },\n    },\n    {\n      name: 'tanstack-react-start:rsc-env-config',\n      config() {\n        return {\n          rsc: {\n            // Disable @vitejs/plugin-rsc's built-in server handler middleware.\n            // TanStack Start has its own request handling via the SSR environment.\n            serverHandler: false,\n            // Disable CSS link precedence to prevent React 19 SSR suspension\n            // TanStack Start handles CSS preloading via manifest injection instead\n            cssLinkPrecedence: false,\n          },\n          environments: {\n            [RSC_ENV_NAME]: {\n              consumer: 'server',\n              // Force @tanstack packages to be processed by Vite as source code\n              // rather than treated as external modules. This ensures:\n              // 1. createIsomorphicFn transforms are applied\n              // 2. Imports are resolved within the RSC environment context\n              //    with proper react-server conditions and pre-bundled deps\n              resolve: {\n                noExternal: [\n                  '@tanstack/start**',\n                  '@tanstack/react-start',\n                  '@tanstack/react-start-rsc',\n                  '@tanstack/react-router',\n                ],\n              },\n              build: {\n                rollupOptions: {\n                  input: {\n                    index: rscEntryPath,\n                  },\n                },\n              },\n            },\n          },\n        } satisfies UserConfig & {\n          rsc: {\n            serverHandler: false\n            cssLinkPrecedence?: boolean\n          }\n        }\n      },\n    },\n\n    // Runtime bridge into the Vite RSC environment.\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-runtime-virtual',\n      moduleId: RSC_RUNTIME_VIRTUAL_ID,\n      load() {\n        const envName = this.environment.name\n        if (envName === RSC_ENV_NAME) {\n          return `export { renderToReadableStream, createFromReadableStream, createTemporaryReferenceSet, decodeReply, loadServerAction, decodeAction, decodeFormState } from '@vitejs/plugin-rsc/rsc'`\n        }\n        return `\nexport function renderToReadableStream() { throw new Error('renderToReadableStream can only be used in RSC environment'); }\nexport function createFromReadableStream() { throw new Error('createFromReadableStream can only be used in RSC environment'); }\nexport function createTemporaryReferenceSet() { throw new Error('createTemporaryReferenceSet can only be used in RSC environment'); }\nexport function decodeReply() { throw new Error('decodeReply can only be used in RSC environment'); }\nexport function loadServerAction() { throw new Error('loadServerAction can only be used in RSC environment'); }\nexport function decodeAction() { throw new Error('decodeAction can only be used in RSC environment'); }\nexport function decodeFormState() { throw new Error('decodeFormState can only be used in RSC environment'); }\n`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-browser-decode-virtual',\n      moduleId: RSC_BROWSER_DECODE_VIRTUAL_ID,\n      load() {\n        return `export { createFromReadableStream, createFromFetch } from '@vitejs/plugin-rsc/browser'`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-ssr-decode-virtual',\n      moduleId: RSC_SSR_DECODE_VIRTUAL_ID,\n      load() {\n        return `export { setOnClientReference, createFromReadableStream } from '@vitejs/plugin-rsc/ssr'`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-hmr-virtual:dev',\n      moduleId: RSC_HMR_VIRTUAL_ID,\n      apply: 'serve',\n      applyToEnvironment: isClientEnvironment,\n      load() {\n        return `\nexport function setupRscHmr() {\nif (!import.meta.hot) {\n  return\n}\n\n  let __invalidateQueued = false\n\n  function __queueInvalidate() {\n    if (__invalidateQueued) return\n    __invalidateQueued = true\n    queueMicrotask(async () => {\n        __invalidateQueued = false\n        try {\n        const router = window.__TSR_ROUTER__\n        if (!router) {\n            console.warn('[rsc:hmr] No router found on window.__TSR_ROUTER__')\n            return\n        }\n        await router.invalidate()\n        } catch (e) {\n        console.warn('[rsc:hmr] Failed to invalidate router:', e)\n        }\n    })\n  }\n\n  import.meta.hot.on('rsc:update', () => {\n    __queueInvalidate()\n  })\n}\n`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-hmr-virtual:prod',\n      moduleId: RSC_HMR_VIRTUAL_ID,\n      applyToEnvironment: isClientEnvironment,\n      apply: 'build',\n      load() {\n        return 'export function setupRscHmr() {} '\n      },\n    }),\n  ]\n}\n"],"mappings":";;;;AASA,IAAM,uBAAuB,QAC3B,IAAI,OAAO,aAAa;AAG1B,IAAM,qBAAqB;AAC3B,IAAM,yBAAyB;AAC/B,IAAM,gCAAgC;AACtC,IAAM,4BAA4B;AAClC,IAAM,eAAe;AAErB,IAAM,aAAa,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;AAC/D,IAAM,WAAW,KAAK,QAAQ,YAAY,MAAM,MAAM,UAAU,QAAQ;AACxE,IAAM,eAAe,KAAK,QAAQ,UAAU,UAAU;AAEtD,SAAgB,eAKd;AAyBA,QAAO;EACL,SAAS;EACT,yBAAyB;EACzB,qBAT0B;GAC1B,MAAM;GACN,uBAAuB;GACvB,aAAa;GACb,YAAY;GACb;EAKC,uBA3BA,CAIE;GACE,QAAQ;IACN,QAAQ;IACR,QAAQ;IACR,WAAW;IACZ;GACD,QAAQ;IACN,QAAQ;IACR,QAAQ;IACR,WAAW;IACZ;GACF,CACF;EAYF;;AAEH,SAAgB,0BAAwC;AACtD,QAAO;EAML;GACE,MAAM;GACN,SAAS;AACP,WAAO,EACL,KAAK,EACH,YAAY,MACb,EACF;;GAEJ;EACD;GACE,MAAM;GACN,SAAS;AACP,WAAO;KACL,KAAK;MAGH,eAAe;MAGf,mBAAmB;MACpB;KACD,cAAc,GACX,eAAe;MACd,UAAU;MAMV,SAAS,EACP,YAAY;OACV;OACA;OACA;OACA;OACD,EACF;MACD,OAAO,EACL,eAAe,EACb,OAAO,EACL,OAAO,cACR,EACF,EACF;MACF,EACF;KACF;;GAOJ;EAGD,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;AAEL,QADgB,KAAK,YAAY,SACjB,aACd,QAAO;AAET,WAAO;;;;;;;;;;GAUV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;AACL,WAAO;;GAEV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;AACL,WAAO;;GAEV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;GACP,oBAAoB;GACpB,OAAO;AACL,WAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,oBAAoB;GACpB,OAAO;GACP,OAAO;AACL,WAAO;;GAEV,CAAC;EACH"}
+{"version":3,"file":"vite.js","names":[],"sources":["../../../src/plugin/vite.ts"],"sourcesContent":["import { fileURLToPath } from 'node:url'\nimport path from 'pathe'\nimport { createVirtualModule } from '@tanstack/start-plugin-core/vite'\nimport { createRscCssCompilerTransforms } from './rscCssTransform'\nimport type {\n  TanStackStartVitePluginCoreOptions,\n  ViteRscForwardSsrResolverStrategy,\n} from '@tanstack/start-plugin-core/vite'\nimport type { PluginOption, UserConfig } from 'vite'\n\nconst isClientEnvironment = (env: { config: { consumer: string } }) =>\n  env.config.consumer === 'client'\n\n// Virtual module ids used by the React Start RSC runtime.\nconst RSC_HMR_VIRTUAL_ID = 'virtual:tanstack-rsc-hmr'\nconst RSC_RUNTIME_VIRTUAL_ID = 'virtual:tanstack-rsc-runtime'\nconst RSC_BROWSER_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-browser-decode'\nconst RSC_SSR_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-ssr-decode'\nconst RSC_ENV_NAME = 'rsc'\n\nconst currentDir = path.dirname(fileURLToPath(import.meta.url))\nconst entryDir = path.resolve(currentDir, '..', '..', 'plugin', 'entry')\nconst rscEntryPath = path.resolve(entryDir, 'rsc.tsx')\n\nexport function configureRsc(): {\n  envName: string\n  providerEnvironmentName: TanStackStartVitePluginCoreOptions['providerEnvironmentName']\n  ssrResolverStrategy: TanStackStartVitePluginCoreOptions['ssrResolverStrategy']\n  serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters']\n  compilerTransforms: TanStackStartVitePluginCoreOptions['compilerTransforms']\n} {\n  const serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters'] =\n    [\n      // IMPORTANT: plugin-adapters-plugin only calls the top-level factory once.\n      // That factory must return a flat array of adapters (not nested arrays),\n      // otherwise router-core ends up with non-adapter entries and Seroval crashes.\n      {\n        client: {\n          module: '@tanstack/react-start/rsc/serialization/client',\n          export: 'rscSerializationAdapter',\n          isFactory: true,\n        },\n        server: {\n          module: '@tanstack/react-start/rsc/serialization/server',\n          export: 'rscSerializationAdapter',\n          isFactory: true,\n        },\n      },\n    ]\n  const ssrResolverStrategy = {\n    type: 'vite-rsc-forward',\n    sourceEnvironmentName: RSC_ENV_NAME,\n    sourceEntry: 'index',\n    exportName: 'getServerFnById',\n  } satisfies ViteRscForwardSsrResolverStrategy\n  return {\n    envName: RSC_ENV_NAME,\n    providerEnvironmentName: RSC_ENV_NAME,\n    ssrResolverStrategy,\n    serializationAdapters,\n    compilerTransforms: createRscCssCompilerTransforms({\n      loadCssExpression: 'import.meta.viteRsc.loadCss()',\n    }),\n  }\n}\nexport function reactStartRscVitePlugin(): PluginOption {\n  return [\n    // When RSC is enabled, SSR needs noExternal: true to ensure single React instance.\n    // The RSC decoder's dynamic imports for client components can cause module duplication\n    // without this, leading to \"Invalid hook call\" errors.\n    // We use the top-level `ssr` config option as `environments.ssr.resolve.noExternal`\n    // doesn't have the same effect.\n    {\n      name: 'tanstack-react-start:rsc-ssr-config',\n      config() {\n        return {\n          ssr: {\n            noExternal: true,\n          },\n        }\n      },\n    },\n    {\n      name: 'tanstack-react-start:rsc-env-config',\n      config() {\n        return {\n          rsc: {\n            // Disable @vitejs/plugin-rsc's built-in server handler middleware.\n            // TanStack Start has its own request handling via the SSR environment.\n            serverHandler: false,\n            // Disable CSS link precedence to prevent React 19 SSR suspension\n            // TanStack Start handles CSS preloading via manifest injection instead\n            cssLinkPrecedence: false,\n          },\n          environments: {\n            [RSC_ENV_NAME]: {\n              consumer: 'server',\n              // Force @tanstack packages to be processed by Vite as source code\n              // rather than treated as external modules. This ensures:\n              // 1. createIsomorphicFn transforms are applied\n              // 2. Imports are resolved within the RSC environment context\n              //    with proper react-server conditions and pre-bundled deps\n              resolve: {\n                noExternal: [\n                  '@tanstack/start**',\n                  '@tanstack/react-start',\n                  '@tanstack/react-start-rsc',\n                  '@tanstack/react-router',\n                ],\n              },\n              build: {\n                rollupOptions: {\n                  input: {\n                    index: rscEntryPath,\n                  },\n                },\n              },\n            },\n          },\n        } satisfies UserConfig & {\n          rsc: {\n            serverHandler: false\n            cssLinkPrecedence?: boolean\n          }\n        }\n      },\n    },\n\n    {\n      name: 'tanstack-react-start:rsc-scan-virtual-fallback',\n      apply: 'build',\n      applyToEnvironment(env) {\n        return env.name === RSC_ENV_NAME\n      },\n      load: {\n        filter: {\n          id: /^(virtual:tanstack-rsc-runtime|virtual:vite-rsc\\/encryption-key)$/,\n        },\n        handler(id) {\n          if (this.environment.config.build.write !== false) return\n\n          if (id === RSC_RUNTIME_VIRTUAL_ID) {\n            return `export { renderToReadableStream, createFromReadableStream, createTemporaryReferenceSet, decodeReply, loadServerAction, decodeAction, decodeFormState } from '@vitejs/plugin-rsc/rsc'`\n          }\n\n          if (id === 'virtual:vite-rsc/encryption-key') {\n            return `export default () => ''`\n          }\n\n          return undefined\n        },\n      },\n    },\n\n    // Runtime bridge into the Vite RSC environment.\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-runtime-virtual',\n      moduleId: RSC_RUNTIME_VIRTUAL_ID,\n      load() {\n        const envName = this.environment.name\n        if (envName === RSC_ENV_NAME) {\n          return `export { renderToReadableStream, createFromReadableStream, createTemporaryReferenceSet, decodeReply, loadServerAction, decodeAction, decodeFormState } from '@vitejs/plugin-rsc/rsc'`\n        }\n        return `\nexport function renderToReadableStream() { throw new Error('renderToReadableStream can only be used in RSC environment'); }\nexport function createFromReadableStream() { throw new Error('createFromReadableStream can only be used in RSC environment'); }\nexport function createTemporaryReferenceSet() { throw new Error('createTemporaryReferenceSet can only be used in RSC environment'); }\nexport function decodeReply() { throw new Error('decodeReply can only be used in RSC environment'); }\nexport function loadServerAction() { throw new Error('loadServerAction can only be used in RSC environment'); }\nexport function decodeAction() { throw new Error('decodeAction can only be used in RSC environment'); }\nexport function decodeFormState() { throw new Error('decodeFormState can only be used in RSC environment'); }\n`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-browser-decode-virtual',\n      moduleId: RSC_BROWSER_DECODE_VIRTUAL_ID,\n      load() {\n        return `export { createFromReadableStream, createFromFetch } from '@vitejs/plugin-rsc/browser'`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-ssr-decode-virtual',\n      moduleId: RSC_SSR_DECODE_VIRTUAL_ID,\n      load() {\n        return `export { setOnClientReference, createFromReadableStream } from '@vitejs/plugin-rsc/ssr'`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-hmr-virtual:dev',\n      moduleId: RSC_HMR_VIRTUAL_ID,\n      apply: 'serve',\n      applyToEnvironment: isClientEnvironment,\n      load() {\n        return `\nexport function setupRscHmr() {\nif (!import.meta.hot) {\n  return\n}\n\n  let __invalidateQueued = false\n\n  function __queueInvalidate() {\n    if (__invalidateQueued) return\n    __invalidateQueued = true\n    queueMicrotask(async () => {\n        __invalidateQueued = false\n        try {\n        const router = window.__TSR_ROUTER__\n        if (!router) {\n            console.warn('[rsc:hmr] No router found on window.__TSR_ROUTER__')\n            return\n        }\n        await router.invalidate()\n        } catch (e) {\n        console.warn('[rsc:hmr] Failed to invalidate router:', e)\n        }\n    })\n  }\n\n  import.meta.hot.on('rsc:update', () => {\n    __queueInvalidate()\n  })\n}\n`\n      },\n    }),\n    createVirtualModule({\n      name: 'tanstack-react-start:rsc-hmr-virtual:prod',\n      moduleId: RSC_HMR_VIRTUAL_ID,\n      applyToEnvironment: isClientEnvironment,\n      apply: 'build',\n      load() {\n        return 'export function setupRscHmr() {} '\n      },\n    }),\n  ]\n}\n"],"mappings":";;;;;AAUA,IAAM,uBAAuB,QAC3B,IAAI,OAAO,aAAa;AAG1B,IAAM,qBAAqB;AAC3B,IAAM,yBAAyB;AAC/B,IAAM,gCAAgC;AACtC,IAAM,4BAA4B;AAClC,IAAM,eAAe;AAErB,IAAM,aAAa,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;AAC/D,IAAM,WAAW,KAAK,QAAQ,YAAY,MAAM,MAAM,UAAU,QAAQ;AACxE,IAAM,eAAe,KAAK,QAAQ,UAAU,UAAU;AAEtD,SAAgB,eAMd;AAyBA,QAAO;EACL,SAAS;EACT,yBAAyB;EACzB,qBAT0B;GAC1B,MAAM;GACN,uBAAuB;GACvB,aAAa;GACb,YAAY;GACb;EAKC,uBA3BA,CAIE;GACE,QAAQ;IACN,QAAQ;IACR,QAAQ;IACR,WAAW;IACZ;GACD,QAAQ;IACN,QAAQ;IACR,QAAQ;IACR,WAAW;IACZ;GACF,CACF;EAYD,oBAAoB,+BAA+B,EACjD,mBAAmB,iCACpB,CAAC;EACH;;AAEH,SAAgB,0BAAwC;AACtD,QAAO;EAML;GACE,MAAM;GACN,SAAS;AACP,WAAO,EACL,KAAK,EACH,YAAY,MACb,EACF;;GAEJ;EACD;GACE,MAAM;GACN,SAAS;AACP,WAAO;KACL,KAAK;MAGH,eAAe;MAGf,mBAAmB;MACpB;KACD,cAAc,GACX,eAAe;MACd,UAAU;MAMV,SAAS,EACP,YAAY;OACV;OACA;OACA;OACA;OACD,EACF;MACD,OAAO,EACL,eAAe,EACb,OAAO,EACL,OAAO,cACR,EACF,EACF;MACF,EACF;KACF;;GAOJ;EAED;GACE,MAAM;GACN,OAAO;GACP,mBAAmB,KAAK;AACtB,WAAO,IAAI,SAAS;;GAEtB,MAAM;IACJ,QAAQ,EACN,IAAI,qEACL;IACD,QAAQ,IAAI;AACV,SAAI,KAAK,YAAY,OAAO,MAAM,UAAU,MAAO;AAEnD,SAAI,OAAO,uBACT,QAAO;AAGT,SAAI,OAAO,kCACT,QAAO;;IAKZ;GACF;EAGD,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;AAEL,QADgB,KAAK,YAAY,SACjB,aACd,QAAO;AAET,WAAO;;;;;;;;;;GAUV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;AACL,WAAO;;GAEV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;AACL,WAAO;;GAEV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,OAAO;GACP,oBAAoB;GACpB,OAAO;AACL,WAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCV,CAAC;EACF,oBAAoB;GAClB,MAAM;GACN,UAAU;GACV,oBAAoB;GACpB,OAAO;GACP,OAAO;AACL,WAAO;;GAEV,CAAC;EACH"}

package/dist/esm/renderServerComponent.js

@@ -1,5 +1,6 @@
 import { RENDERABLE_RSC, SERVER_COMPONENT_STREAM } from "./ServerComponentTypes.js";
 import { ReplayableStream } from "./ReplayableStream.js";
+import { createRscCssEnvelope } from "./rscCssEnvelope.js";
 import { renderToReadableStream } from "virtual:tanstack-rsc-runtime";
 import { getRequest } from "@tanstack/start-server-core";
 import { getStartContext } from "@tanstack/start-storage-context";
@@ -27,8 +28,8 @@ import { getStartContext } from "@tanstack/start-storage-context";
 * )
 * ```
 */
-async function renderServerComponent(node) {
-	const flightStream = renderToReadableStream(node);
+async function renderServerComponent(node, options) {
+	const flightStream = renderToReadableStream(createRscCssEnvelope(node, options));
 	const isRouterRequest = getStartContext({ throwIfNotFound: false })?.handlerType === "router";
 	const ssrHandler = globalThis.__RSC_SSR__;
 	if (isRouterRequest && ssrHandler) {

package/dist/esm/renderServerComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"renderServerComponent.js","names":[],"sources":["../../src/renderServerComponent.ts"],"sourcesContent":["import { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'\nimport { getRequest } from '@tanstack/start-server-core'\nimport { getStartContext } from '@tanstack/start-storage-context'\nimport { ReplayableStream } from './ReplayableStream'\nimport { RENDERABLE_RSC, SERVER_COMPONENT_STREAM } from './ServerComponentTypes'\nimport type {\n  AnyRenderableServerComponent,\n  RenderableServerComponentBuilder,\n  ServerComponentStream,\n  ValidateRenderableServerComponent,\n} from './ServerComponentTypes'\n\nimport './rscSsrHandler'\n// Import for global declaration side effect\nexport type { RscSsrHandler, RscDecodeResult } from './rscSsrHandler'\n\n/**\n * Renderable RSC handle type - used for serialization detection.\n */\n\n/**\n * Type guard for renderable RSC handle.\n */\nexport function isRenderableRscHandle(\n  value: unknown,\n): value is AnyRenderableServerComponent {\n  return (\n    typeof value === 'function' &&\n    SERVER_COMPONENT_STREAM in value &&\n    RENDERABLE_RSC in value &&\n    (value as any)[RENDERABLE_RSC] === true\n  )\n}\n\n/**\n * Renders a React element to an RSC Flight stream.\n *\n * Returns a \"renderable proxy\" that can be:\n * - Rendered directly as `{data}` in JSX\n * - Accessed for nested selections: `{data.foo.bar.Hello}`\n *\n * No slot support - for slots use `createCompositeComponent`.\n *\n * @example\n * ```tsx\n * // In a loader or server function\n * const data = await renderServerComponent(<MyServerComponent foo=\"bar\" />)\n *\n * // In the route component\n * return (\n *   <div>\n *     {data}\n *     {data.sidebar.Menu}\n *   </div>\n * )\n * ```\n */\nexport async function renderServerComponent<TNode>(\n  node: ValidateRenderableServerComponent<TNode>,\n): Promise<RenderableServerComponentBuilder<TNode>> {\n  const flightStream = renderToReadableStream(node)\n\n  // Check if this is an SSR request (router) or a direct server function call\n  const ctx = getStartContext({ throwIfNotFound: false })\n  const isRouterRequest = ctx?.handlerType === 'router'\n  const ssrHandler = globalThis.__RSC_SSR__\n\n  // SSR path: buffer stream for replay, pre-decode for synchronous rendering\n  if (isRouterRequest && ssrHandler) {\n    const signal = getRequest().signal\n    const stream = new ReplayableStream(flightStream, { signal })\n\n    // Pre-decode during loader phase for synchronous SSR rendering\n    const decoded = await ssrHandler.decode(stream)\n    return ssrHandler.createRenderableProxy(\n      stream,\n      decoded,\n    ) as RenderableServerComponentBuilder<TNode>\n  }\n\n  // Server function call path: return a handle for serialization\n  return createRenderableHandle(\n    flightStream,\n  ) as unknown as RenderableServerComponentBuilder<TNode>\n}\n\n/**\n * Creates a renderable handle for server function responses.\n * Tagged with RENDERABLE_RSC for the serialization adapter.\n */\nfunction createRenderableHandle(\n  flightStream: ReadableStream<Uint8Array>,\n): AnyRenderableServerComponent {\n  const streamWrapper: ServerComponentStream = {\n    createReplayStream: () => flightStream,\n  }\n\n  const stub = function RenderableRscStub(): never {\n    throw new Error(\n      'Renderable RSC from server function cannot be rendered on server. ' +\n        'It should be serialized and sent to the client.',\n    )\n  }\n\n  ;(stub as any)[SERVER_COMPONENT_STREAM] = streamWrapper\n  ;(stub as any)[RENDERABLE_RSC] = true\n  return stub as unknown as AnyRenderableServerComponent\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,eAAsB,sBACpB,MACkD;CAClD,MAAM,eAAe,uBAAuB,KAAK;CAIjD,MAAM,kBADM,gBAAgB,EAAE,iBAAiB,OAAO,CAAC,EAC1B,gBAAgB;CAC7C,MAAM,aAAa,WAAW;AAG9B,KAAI,mBAAmB,YAAY;EACjC,MAAM,SAAS,YAAY,CAAC;EAC5B,MAAM,SAAS,IAAI,iBAAiB,cAAc,EAAE,QAAQ,CAAC;EAG7D,MAAM,UAAU,MAAM,WAAW,OAAO,OAAO;AAC/C,SAAO,WAAW,sBAChB,QACA,QACD;;AAIH,QAAO,uBACL,aACD;;;;;;AAOH,SAAS,uBACP,cAC8B;CAC9B,MAAM,gBAAuC,EAC3C,0BAA0B,cAC3B;CAED,MAAM,OAAO,SAAS,oBAA2B;AAC/C,QAAM,IAAI,MACR,oHAED;;AAGD,MAAa,2BAA2B;AACxC,MAAa,kBAAkB;AACjC,QAAO"}
+{"version":3,"file":"renderServerComponent.js","names":[],"sources":["../../src/renderServerComponent.ts"],"sourcesContent":["import { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'\nimport { getRequest } from '@tanstack/start-server-core'\nimport { getStartContext } from '@tanstack/start-storage-context'\nimport { ReplayableStream } from './ReplayableStream'\nimport { RENDERABLE_RSC, SERVER_COMPONENT_STREAM } from './ServerComponentTypes'\nimport { createRscCssEnvelope } from './rscCssEnvelope'\nimport type {\n  AnyRenderableServerComponent,\n  RenderableServerComponentBuilder,\n  ServerComponentStream,\n  ValidateRenderableServerComponent,\n} from './ServerComponentTypes'\nimport type { RscCssEnvelopeOptions } from './rscCssEnvelope'\n\nimport './rscSsrHandler'\n// Import for global declaration side effect\nexport type { RscSsrHandler, RscDecodeResult } from './rscSsrHandler'\n\n/**\n * Renderable RSC handle type - used for serialization detection.\n */\n\n/**\n * Type guard for renderable RSC handle.\n */\nexport function isRenderableRscHandle(\n  value: unknown,\n): value is AnyRenderableServerComponent {\n  return (\n    typeof value === 'function' &&\n    SERVER_COMPONENT_STREAM in value &&\n    RENDERABLE_RSC in value &&\n    (value as any)[RENDERABLE_RSC] === true\n  )\n}\n\n/**\n * Renders a React element to an RSC Flight stream.\n *\n * Returns a \"renderable proxy\" that can be:\n * - Rendered directly as `{data}` in JSX\n * - Accessed for nested selections: `{data.foo.bar.Hello}`\n *\n * No slot support - for slots use `createCompositeComponent`.\n *\n * @example\n * ```tsx\n * // In a loader or server function\n * const data = await renderServerComponent(<MyServerComponent foo=\"bar\" />)\n *\n * // In the route component\n * return (\n *   <div>\n *     {data}\n *     {data.sidebar.Menu}\n *   </div>\n * )\n * ```\n */\nexport async function renderServerComponent<TNode>(\n  node: ValidateRenderableServerComponent<TNode>,\n  options?: RscCssEnvelopeOptions,\n): Promise<RenderableServerComponentBuilder<TNode>> {\n  const flightStream = renderToReadableStream(\n    createRscCssEnvelope(node, options),\n  )\n\n  // Check if this is an SSR request (router) or a direct server function call\n  const ctx = getStartContext({ throwIfNotFound: false })\n  const isRouterRequest = ctx?.handlerType === 'router'\n  const ssrHandler = globalThis.__RSC_SSR__\n\n  // SSR path: buffer stream for replay, pre-decode for synchronous rendering\n  if (isRouterRequest && ssrHandler) {\n    const signal = getRequest().signal\n    const stream = new ReplayableStream(flightStream, { signal })\n\n    // Pre-decode during loader phase for synchronous SSR rendering\n    const decoded = await ssrHandler.decode(stream)\n    return ssrHandler.createRenderableProxy(\n      stream,\n      decoded,\n    ) as RenderableServerComponentBuilder<TNode>\n  }\n\n  // Server function call path: return a handle for serialization\n  return createRenderableHandle(\n    flightStream,\n  ) as unknown as RenderableServerComponentBuilder<TNode>\n}\n\n/**\n * Creates a renderable handle for server function responses.\n * Tagged with RENDERABLE_RSC for the serialization adapter.\n */\nfunction createRenderableHandle(\n  flightStream: ReadableStream<Uint8Array>,\n): AnyRenderableServerComponent {\n  const streamWrapper: ServerComponentStream = {\n    createReplayStream: () => flightStream,\n  }\n\n  const stub = function RenderableRscStub(): never {\n    throw new Error(\n      'Renderable RSC from server function cannot be rendered on server. ' +\n        'It should be serialized and sent to the client.',\n    )\n  }\n\n  ;(stub as any)[SERVER_COMPONENT_STREAM] = streamWrapper\n  ;(stub as any)[RENDERABLE_RSC] = true\n  return stub as unknown as AnyRenderableServerComponent\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,eAAsB,sBACpB,MACA,SACkD;CAClD,MAAM,eAAe,uBACnB,qBAAqB,MAAM,QAAQ,CACpC;CAID,MAAM,kBADM,gBAAgB,EAAE,iBAAiB,OAAO,CAAC,EAC1B,gBAAgB;CAC7C,MAAM,aAAa,WAAW;AAG9B,KAAI,mBAAmB,YAAY;EACjC,MAAM,SAAS,YAAY,CAAC;EAC5B,MAAM,SAAS,IAAI,iBAAiB,cAAc,EAAE,QAAQ,CAAC;EAG7D,MAAM,UAAU,MAAM,WAAW,OAAO,OAAO;AAC/C,SAAO,WAAW,sBAChB,QACA,QACD;;AAIH,QAAO,uBACL,aACD;;;;;;AAOH,SAAS,uBACP,cAC8B;CAC9B,MAAM,gBAAuC,EAC3C,0BAA0B,cAC3B;CAED,MAAM,OAAO,SAAS,oBAA2B;AAC/C,QAAM,IAAI,MACR,oHAED;;AAGD,MAAa,2BAA2B;AACxC,MAAa,kBAAkB;AACjC,QAAO"}

package/dist/esm/rscCssEnvelope.js

@@ -0,0 +1,23 @@
+//#region src/rscCssEnvelope.ts
+var RSC_CSS_ENVELOPE_MARKER = "__tanstackStartRscCssEnvelope";
+var RSC_CSS_ENVELOPE_RESOURCES = "__tanstackStartRscCss";
+var RSC_CSS_ENVELOPE_VALUE = "__tanstackStartRscValue";
+function createRscCssEnvelope(value, options) {
+	const resources = options?.[RSC_CSS_ENVELOPE_RESOURCES];
+	if (resources === void 0 || resources === null || resources === false) return value;
+	return {
+		[RSC_CSS_ENVELOPE_MARKER]: true,
+		[RSC_CSS_ENVELOPE_RESOURCES]: resources,
+		[RSC_CSS_ENVELOPE_VALUE]: value
+	};
+}
+function unwrapRscCssEnvelope(value) {
+	if (!value || typeof value !== "object") return value;
+	const maybeEnvelope = value;
+	if (maybeEnvelope[RSC_CSS_ENVELOPE_MARKER] !== true) return value;
+	return maybeEnvelope[RSC_CSS_ENVELOPE_VALUE];
+}
+//#endregion
+export { createRscCssEnvelope, unwrapRscCssEnvelope };
+
+//# sourceMappingURL=rscCssEnvelope.js.map

package/dist/esm/rscCssEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rscCssEnvelope.js","names":[],"sources":["../../src/rscCssEnvelope.ts"],"sourcesContent":["import type React from 'react'\n\nconst RSC_CSS_ENVELOPE_MARKER = '__tanstackStartRscCssEnvelope'\nconst RSC_CSS_ENVELOPE_RESOURCES = '__tanstackStartRscCss'\nconst RSC_CSS_ENVELOPE_VALUE = '__tanstackStartRscValue'\n\nexport interface RscCssEnvelopeOptions {\n  [RSC_CSS_ENVELOPE_RESOURCES]?: React.ReactNode\n}\n\nexport function createRscCssEnvelope<TValue>(\n  value: TValue,\n  options?: RscCssEnvelopeOptions,\n): TValue | Record<string, unknown> {\n  const resources = options?.[RSC_CSS_ENVELOPE_RESOURCES]\n  if (resources === undefined || resources === null || resources === false) {\n    return value\n  }\n\n  return {\n    [RSC_CSS_ENVELOPE_MARKER]: true,\n    [RSC_CSS_ENVELOPE_RESOURCES]: resources,\n    [RSC_CSS_ENVELOPE_VALUE]: value,\n  }\n}\n\nexport function unwrapRscCssEnvelope(value: unknown): unknown {\n  if (!value || typeof value !== 'object') {\n    return value\n  }\n\n  const maybeEnvelope = value as Record<string, unknown>\n  if (maybeEnvelope[RSC_CSS_ENVELOPE_MARKER] !== true) {\n    return value\n  }\n\n  return maybeEnvelope[RSC_CSS_ENVELOPE_VALUE]\n}\n"],"mappings":";AAEA,IAAM,0BAA0B;AAChC,IAAM,6BAA6B;AACnC,IAAM,yBAAyB;AAM/B,SAAgB,qBACd,OACA,SACkC;CAClC,MAAM,YAAY,UAAU;AAC5B,KAAI,cAAc,KAAA,KAAa,cAAc,QAAQ,cAAc,MACjE,QAAO;AAGT,QAAO;GACJ,0BAA0B;GAC1B,6BAA6B;GAC7B,yBAAyB;EAC3B;;AAGH,SAAgB,qBAAqB,OAAyB;AAC5D,KAAI,CAAC,SAAS,OAAO,UAAU,SAC7B,QAAO;CAGT,MAAM,gBAAgB;AACtB,KAAI,cAAc,6BAA6B,KAC7C,QAAO;AAGT,QAAO,cAAc"}

package/dist/esm/serialization.server.js

@@ -1,4 +1,5 @@
 import { RENDERABLE_RSC, RSC_SLOT_USAGES_STREAM, SERVER_COMPONENT_STREAM, isServerComponent } from "./ServerComponentTypes.js";
+import { unwrapRscCssEnvelope } from "./rscCssEnvelope.js";
 import { awaitLazyElements } from "./awaitLazyElements.js";
 import { createRscProxy } from "./createRscProxy.js";
 import { getStartContext } from "@tanstack/start-storage-context";
@@ -17,7 +18,8 @@ setOnClientReference(({ deps, runtime }) => {
 	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));
+	const seenHrefs = /* @__PURE__ */ new Set();
+	for (const asset of ctx.requestAssets) if (asset.tag === "link" && asset.attrs?.href) seenHrefs.add(asset.attrs.href);
 	for (const href of deps.js) {
 		if (seenHrefs.has(href)) continue;
 		seenHrefs.add(href);
@@ -49,12 +51,12 @@ var ssrHandler = {
 		const jsCollector = /* @__PURE__ */ new Set();
 		return decodeCollectorStorage.run(cssCollector, async () => {
 			return jsCollectorStorage.run(jsCollector, async () => {
-				const tree = await createFromReadableStream(readableStream);
-				await awaitLazyElements(tree, (href) => {
+				const decodedTree = await createFromReadableStream(readableStream);
+				await awaitLazyElements(decodedTree, (href) => {
 					cssCollector.add(href);
 				});
 				return {
-					tree,
+					tree: unwrapRscCssEnvelope(decodedTree),
 					cssHrefs: cssCollector.size > 0 ? cssCollector : void 0,
 					jsPreloads: jsCollector.size > 0 ? jsCollector : void 0
 				};

package/dist/esm/serialization.server.js.map

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

package/dist/esm/src/createCompositeComponent.d.ts

@@ -1,4 +1,5 @@
 import { CompositeComponentResult, ValidateCompositeComponent } from './ServerComponentTypes.js';
+import { RscCssEnvelopeOptions } from './rscCssEnvelope.js';
 /**
  * Creates a composite server component with slot support.
  *
@@ -29,4 +30,4 @@ import { CompositeComponentResult, ValidateCompositeComponent } from './ServerCo
  * )
  * ```
  */
-export declare function createCompositeComponent<TComp>(component: ValidateCompositeComponent<TComp>): Promise<CompositeComponentResult<TComp>>;
+export declare function createCompositeComponent<TComp>(component: ValidateCompositeComponent<TComp>, options?: RscCssEnvelopeOptions): Promise<CompositeComponentResult<TComp>>;

package/dist/esm/src/plugin/rscCssTransform.d.ts

@@ -0,0 +1,5 @@
+import { StartCompilerImportTransform } from '@tanstack/start-plugin-core';
+export declare function createRscCssCompilerTransforms(opts: {
+    loadCssExpression: string;
+    serverFnProviderOnly?: boolean | undefined;
+}): Array<StartCompilerImportTransform>;

package/dist/esm/src/plugin/vite.d.ts

@@ -5,5 +5,6 @@ export declare function configureRsc(): {
     providerEnvironmentName: TanStackStartVitePluginCoreOptions['providerEnvironmentName'];
     ssrResolverStrategy: TanStackStartVitePluginCoreOptions['ssrResolverStrategy'];
     serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters'];
+    compilerTransforms: TanStackStartVitePluginCoreOptions['compilerTransforms'];
 };
 export declare function reactStartRscVitePlugin(): PluginOption;

package/dist/esm/src/renderServerComponent.d.ts

@@ -1,4 +1,5 @@
 import { AnyRenderableServerComponent, RenderableServerComponentBuilder, ValidateRenderableServerComponent } from './ServerComponentTypes.js';
+import { RscCssEnvelopeOptions } from './rscCssEnvelope.js';
 export type { RscSsrHandler, RscDecodeResult } from './rscSsrHandler.js';
 /**
  * Renderable RSC handle type - used for serialization detection.
@@ -30,4 +31,4 @@ export declare function isRenderableRscHandle(value: unknown): value is AnyRende
  * )
  * ```
  */
-export declare function renderServerComponent<TNode>(node: ValidateRenderableServerComponent<TNode>): Promise<RenderableServerComponentBuilder<TNode>>;
+export declare function renderServerComponent<TNode>(node: ValidateRenderableServerComponent<TNode>, options?: RscCssEnvelopeOptions): Promise<RenderableServerComponentBuilder<TNode>>;

package/dist/esm/src/rscCssEnvelope.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+declare const RSC_CSS_ENVELOPE_RESOURCES = "__tanstackStartRscCss";
+export interface RscCssEnvelopeOptions {
+    [RSC_CSS_ENVELOPE_RESOURCES]?: React.ReactNode;
+}
+export declare function createRscCssEnvelope<TValue>(value: TValue, options?: RscCssEnvelopeOptions): TValue | Record<string, unknown>;
+export declare function unwrapRscCssEnvelope(value: unknown): unknown;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-start-rsc",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "description": "React Server Components support for TanStack Start",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -53,6 +53,12 @@
         "default": "./dist/esm/plugin/vite.js"
       }
     },
+    "./plugin/rscCssTransform": {
+      "import": {
+        "types": "./dist/esm/src/plugin/rscCssTransform.d.ts",
+        "default": "./dist/esm/plugin/rscCssTransform.js"
+      }
+    },
     "./rsbuild/ssr-decode": {
       "import": {
         "types": "./dist/esm/src/rsbuild/ssr-decode.d.ts",
@@ -77,12 +83,12 @@
   "dependencies": {
     "pathe": "^2.0.3",
     "@tanstack/react-router": "1.169.1",
-    "@tanstack/router-core": "1.169.1",
     "@tanstack/react-start-server": "1.166.48",
+    "@tanstack/router-core": "1.169.1",
     "@tanstack/router-utils": "1.161.7",
     "@tanstack/start-client-core": "1.168.1",
+    "@tanstack/start-plugin-core": "1.169.13",
     "@tanstack/start-fn-stubs": "1.161.6",
-    "@tanstack/start-plugin-core": "1.169.12",
     "@tanstack/start-server-core": "1.167.26",
     "@tanstack/start-storage-context": "1.166.34"
   },

package/src/createCompositeComponent.ts

@@ -9,6 +9,7 @@ import {
   RSC_SLOT_USAGES_STREAM,
   SERVER_COMPONENT_STREAM,
 } from './ServerComponentTypes'
+import { createRscCssEnvelope } from './rscCssEnvelope'
 import type {
   AnyCompositeComponent,
   CompositeComponentResult,
@@ -16,6 +17,7 @@ import type {
   ServerComponentStream,
   ValidateCompositeComponent,
 } from './ServerComponentTypes'
+import type { RscCssEnvelopeOptions } from './rscCssEnvelope'
 
 import './rscSsrHandler' // Import for global declaration side effect
 
@@ -51,6 +53,7 @@ import './rscSsrHandler' // Import for global declaration side effect
  */
 export async function createCompositeComponent<TComp>(
   component: ValidateCompositeComponent<TComp>,
+  options?: RscCssEnvelopeOptions,
 ): Promise<CompositeComponentResult<TComp>> {
   const isDev = process.env.NODE_ENV === 'development'
 
@@ -76,14 +79,17 @@ export async function createCompositeComponent<TComp>(
 
   // Wrapper that renders the user's component inside Flight render context
   async function ServerComponentWrapper() {
-    return (component as React.FC)(proxyProps)
+    return createRscCssEnvelope(
+      await (component as React.FC)(proxyProps),
+      options,
+    )
   }
 
   // Render using createElement so React calls our component during Flight rendering
   // This is critical for React.cache to work - the component must be invoked
   // during renderToReadableStream's execution, not before
   const flightStream = renderToReadableStream(
-    createElement(ServerComponentWrapper),
+    createElement(ServerComponentWrapper as any),
   )
 
   // Check if this is an SSR request (router) or a direct server function call

package/src/createServerComponentFromStream.ts

@@ -6,6 +6,7 @@ import { createFromReadableStream as browserDecode } from 'virtual:tanstack-rsc-
 
 import { awaitLazyElements } from './awaitLazyElements'
 import { createRscProxy } from './createRscProxy'
+import { unwrapRscCssEnvelope } from './rscCssEnvelope'
 import type {
   AnyCompositeComponent,
   RscSlotUsageEvent,
@@ -80,9 +81,9 @@ function setupStreamDecode(stream: ReadableStream<Uint8Array>): {
       await awaitLazyElements(result, (href) => {
         cssHrefs.add(href)
       })
-      cachedTree = result
+      cachedTree = unwrapRscCssEnvelope(result)
       cacheReady = true
-      return result
+      return cachedTree
     },
   )
 

package/src/plugin/rscCssTransform.ts

@@ -0,0 +1,150 @@
+import type {
+  StartCompilerImportTransform,
+  StartCompilerTransformContext,
+} from '@tanstack/start-plugin-core'
+
+const TSS_SERVERFN_SPLIT_PARAM = 'tss-serverfn-split'
+const RSC_CSS_OPTIONS_KEY = '__tanstackStartRscCss'
+
+type BabelTypes = StartCompilerTransformContext['types']
+type BabelExpression = ReturnType<
+  StartCompilerTransformContext['parseExpression']
+>
+
+type RscCssTransformKind =
+  | 'renderServerComponent'
+  | 'createCompositeComponent'
+  | 'renderToReadableStream'
+
+export function createRscCssCompilerTransforms(opts: {
+  loadCssExpression: string
+  serverFnProviderOnly?: boolean | undefined
+}): Array<StartCompilerImportTransform> {
+  let loadCssExpression: BabelExpression | undefined
+
+  const getLoadCssExpression = (context: StartCompilerTransformContext) => {
+    loadCssExpression ??= context.parseExpression(opts.loadCssExpression)
+    return loadCssExpression
+  }
+
+  return [
+    createRscCssCompilerTransform({
+      serverFnProviderOnly: opts.serverFnProviderOnly,
+      getLoadCssExpression,
+      kind: 'renderServerComponent',
+      name: 'react-rsc-render-server-component-css',
+    }),
+    createRscCssCompilerTransform({
+      serverFnProviderOnly: opts.serverFnProviderOnly,
+      getLoadCssExpression,
+      kind: 'createCompositeComponent',
+      name: 'react-rsc-create-composite-component-css',
+    }),
+    createRscCssCompilerTransform({
+      serverFnProviderOnly: opts.serverFnProviderOnly,
+      getLoadCssExpression,
+      kind: 'renderToReadableStream',
+      name: 'react-rsc-render-to-readable-stream-css',
+    }),
+  ]
+}
+
+function createRscCssCompilerTransform(opts: {
+  name: string
+  kind: RscCssTransformKind
+  getLoadCssExpression: (
+    context: StartCompilerTransformContext,
+  ) => BabelExpression
+  serverFnProviderOnly?: boolean | undefined
+}): StartCompilerImportTransform {
+  return {
+    name: opts.name,
+    environment: 'server',
+    imports: [
+      {
+        libName: '@tanstack/react-start/rsc',
+        rootExport: opts.kind,
+      },
+      {
+        libName: '@tanstack/react-start-rsc',
+        rootExport: opts.kind,
+      },
+    ],
+    detect: new RegExp(`\\b${opts.kind}\\b`),
+    transform: (candidates, context) => {
+      if (
+        opts.serverFnProviderOnly &&
+        !context.id.includes(TSS_SERVERFN_SPLIT_PARAM)
+      ) {
+        return
+      }
+
+      const t = context.types
+      const loadCssExpression = opts.getLoadCssExpression(context)
+      const cloneLoadCssExpression = () => t.cloneNode(loadCssExpression)
+
+      for (const candidate of candidates) {
+        const args = candidate.path.node.arguments
+        if (args.length !== 1) continue
+
+        if (opts.kind === 'renderToReadableStream') {
+          const firstArg = args[0]
+          if (!firstArg || !t.isExpression(firstArg)) continue
+          if (!isTopLevelJsx(t, firstArg)) continue
+
+          args[0] = createCssFragment(
+            t,
+            firstArg,
+            cloneLoadCssExpression(),
+          ) as typeof firstArg
+          continue
+        }
+
+        args.push(
+          t.objectExpression([
+            t.objectProperty(
+              t.identifier(RSC_CSS_OPTIONS_KEY),
+              cloneLoadCssExpression(),
+            ),
+          ]),
+        )
+      }
+    },
+  }
+}
+
+function isTopLevelJsx(t: BabelTypes, expr: BabelExpression): boolean {
+  const unwrapped = unwrapTransparentExpression(t, expr)
+  return t.isJSXElement(unwrapped) || t.isJSXFragment(unwrapped)
+}
+
+function unwrapTransparentExpression(
+  t: BabelTypes,
+  expr: BabelExpression,
+): BabelExpression {
+  let current = expr
+  while (
+    t.isParenthesizedExpression(current) ||
+    t.isTSAsExpression(current) ||
+    t.isTSSatisfiesExpression(current) ||
+    t.isTSTypeAssertion(current) ||
+    t.isTSNonNullExpression(current)
+  ) {
+    current = current.expression
+  }
+  return current
+}
+
+function createCssFragment(
+  t: BabelTypes,
+  original: BabelExpression,
+  loadCssExpression: BabelExpression,
+) {
+  const unwrapped = unwrapTransparentExpression(t, original)
+  return t.jsxFragment(t.jsxOpeningFragment(), t.jsxClosingFragment(), [
+    t.jsxExpressionContainer(loadCssExpression),
+    t.isJSXElement(unwrapped) || t.isJSXFragment(unwrapped)
+      ? unwrapped
+      : t.jsxExpressionContainer(original),
+  ])
+}

package/src/plugin/vite.ts

@@ -1,6 +1,7 @@
 import { fileURLToPath } from 'node:url'
 import path from 'pathe'
 import { createVirtualModule } from '@tanstack/start-plugin-core/vite'
+import { createRscCssCompilerTransforms } from './rscCssTransform'
 import type {
   TanStackStartVitePluginCoreOptions,
   ViteRscForwardSsrResolverStrategy,
@@ -26,6 +27,7 @@ export function configureRsc(): {
   providerEnvironmentName: TanStackStartVitePluginCoreOptions['providerEnvironmentName']
   ssrResolverStrategy: TanStackStartVitePluginCoreOptions['ssrResolverStrategy']
   serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters']
+  compilerTransforms: TanStackStartVitePluginCoreOptions['compilerTransforms']
 } {
   const serializationAdapters: TanStackStartVitePluginCoreOptions['serializationAdapters'] =
     [
@@ -56,6 +58,9 @@ export function configureRsc(): {
     providerEnvironmentName: RSC_ENV_NAME,
     ssrResolverStrategy,
     serializationAdapters,
+    compilerTransforms: createRscCssCompilerTransforms({
+      loadCssExpression: 'import.meta.viteRsc.loadCss()',
+    }),
   }
 }
 export function reactStartRscVitePlugin(): PluginOption {
@@ -121,6 +126,32 @@ export function reactStartRscVitePlugin(): PluginOption {
       },
     },
 
+    {
+      name: 'tanstack-react-start:rsc-scan-virtual-fallback',
+      apply: 'build',
+      applyToEnvironment(env) {
+        return env.name === RSC_ENV_NAME
+      },
+      load: {
+        filter: {
+          id: /^(virtual:tanstack-rsc-runtime|virtual:vite-rsc\/encryption-key)$/,
+        },
+        handler(id) {
+          if (this.environment.config.build.write !== false) return
+
+          if (id === RSC_RUNTIME_VIRTUAL_ID) {
+            return `export { renderToReadableStream, createFromReadableStream, createTemporaryReferenceSet, decodeReply, loadServerAction, decodeAction, decodeFormState } from '@vitejs/plugin-rsc/rsc'`
+          }
+
+          if (id === 'virtual:vite-rsc/encryption-key') {
+            return `export default () => ''`
+          }
+
+          return undefined
+        },
+      },
+    },
+
     // Runtime bridge into the Vite RSC environment.
     createVirtualModule({
       name: 'tanstack-react-start:rsc-runtime-virtual',

package/src/renderServerComponent.ts

@@ -3,12 +3,14 @@ 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 { createRscCssEnvelope } from './rscCssEnvelope'
 import type {
   AnyRenderableServerComponent,
   RenderableServerComponentBuilder,
   ServerComponentStream,
   ValidateRenderableServerComponent,
 } from './ServerComponentTypes'
+import type { RscCssEnvelopeOptions } from './rscCssEnvelope'
 
 import './rscSsrHandler'
 // Import for global declaration side effect
@@ -57,8 +59,11 @@ export function isRenderableRscHandle(
  */
 export async function renderServerComponent<TNode>(
   node: ValidateRenderableServerComponent<TNode>,
+  options?: RscCssEnvelopeOptions,
 ): Promise<RenderableServerComponentBuilder<TNode>> {
-  const flightStream = renderToReadableStream(node)
+  const flightStream = renderToReadableStream(
+    createRscCssEnvelope(node, options),
+  )
 
   // Check if this is an SSR request (router) or a direct server function call
   const ctx = getStartContext({ throwIfNotFound: false })

package/src/rscCssEnvelope.ts

@@ -0,0 +1,38 @@
+import type React from 'react'
+
+const RSC_CSS_ENVELOPE_MARKER = '__tanstackStartRscCssEnvelope'
+const RSC_CSS_ENVELOPE_RESOURCES = '__tanstackStartRscCss'
+const RSC_CSS_ENVELOPE_VALUE = '__tanstackStartRscValue'
+
+export interface RscCssEnvelopeOptions {
+  [RSC_CSS_ENVELOPE_RESOURCES]?: React.ReactNode
+}
+
+export function createRscCssEnvelope<TValue>(
+  value: TValue,
+  options?: RscCssEnvelopeOptions,
+): TValue | Record<string, unknown> {
+  const resources = options?.[RSC_CSS_ENVELOPE_RESOURCES]
+  if (resources === undefined || resources === null || resources === false) {
+    return value
+  }
+
+  return {
+    [RSC_CSS_ENVELOPE_MARKER]: true,
+    [RSC_CSS_ENVELOPE_RESOURCES]: resources,
+    [RSC_CSS_ENVELOPE_VALUE]: value,
+  }
+}
+
+export function unwrapRscCssEnvelope(value: unknown): unknown {
+  if (!value || typeof value !== 'object') {
+    return value
+  }
+
+  const maybeEnvelope = value as Record<string, unknown>
+  if (maybeEnvelope[RSC_CSS_ENVELOPE_MARKER] !== true) {
+    return value
+  }
+
+  return maybeEnvelope[RSC_CSS_ENVELOPE_VALUE]
+}

package/src/serialization.server.ts

@@ -14,6 +14,7 @@ import {
 } from './ServerComponentTypes'
 import { createRscProxy } from './createRscProxy'
 import { awaitLazyElements } from './awaitLazyElements'
+import { unwrapRscCssEnvelope } from './rscCssEnvelope'
 import type {
   AnyCompositeComponent,
   ServerComponentStream,
@@ -62,11 +63,12 @@ setOnClientReference(
     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),
-    )
+    const seenHrefs = new Set<string>()
+    for (const asset of ctx.requestAssets) {
+      if (asset.tag === 'link' && asset.attrs?.href) {
+        seenHrefs.add(asset.attrs.href as string)
+      }
+    }
 
     for (const href of deps.js) {
       if (seenHrefs.has(href)) continue
@@ -100,13 +102,13 @@ const ssrHandler: RscSsrHandler = {
 
     return decodeCollectorStorage.run(cssCollector, async () => {
       return jsCollectorStorage.run(jsCollector, async () => {
-        const tree = await ssrDecode(readableStream)
-        await awaitLazyElements(tree, (href) => {
+        const decodedTree = await ssrDecode(readableStream)
+        await awaitLazyElements(decodedTree, (href) => {
           cssCollector.add(href)
         })
 
         return {
-          tree,
+          tree: unwrapRscCssEnvelope(decodedTree),
           cssHrefs: cssCollector.size > 0 ? cssCollector : undefined,
           jsPreloads: jsCollector.size > 0 ? jsCollector : undefined,
         }