Open History to see the last commit
1'use client'
2β
3import { use } from 'react'
4import { trackPostProcessPromise } from '@tanstack/start-client-core'
5import { createFromReadableStream as browserDecode } from 'virtual:tanstack-rsc-browser-decode'
6β
7import { awaitLazyElements } from './awaitLazyElements'
8import { createRscProxy } from './createRscProxy'
9import { unwrapRscCssEnvelope } from './rscCssEnvelope'
10import type {
11 AnyCompositeComponent,
12 RscSlotUsageEvent,
13 ServerComponentStream,
14} from './ServerComponentTypes'
15β
16type StreamDecodeOptions = {
17 cssHrefs?: Iterable<string>
18 jsPreloads?: Iterable<string>
19}
20β
21/**
22 * Creates a renderable RSC proxy from a raw Flight stream.
23 * Client-side only - used by the client serialization adapter for `renderServerComponent`.
24 *
25 * Returns a Proxy that:
26 * - Can be rendered directly as `{data}` in JSX
27 * - Supports nested access: `{data.foo.bar}`
28 * - Masquerades as a React element
29 */
30export function createRenderableFromStream(
31 stream: ReadableStream<Uint8Array>,
32 options?: StreamDecodeOptions,
33): any {
34 const { getTree, streamWrapper, cssHrefs, jsPreloads } = setupStreamDecode(
35 stream,
36 options,
37 )
38β
39 return createRscProxy(getTree, {
40 stream: streamWrapper,
41 cssHrefs,
42 jsPreloads,
43 renderable: true,
44 })
45}
46β
47/**
48 * Creates a composite RSC proxy from a raw Flight stream.
49 * Client-side only - used by the client serialization adapter for `createCompositeComponent`.
50 *
51 * Returns a Proxy that:
52 * - NOT directly renderable
53 * - Supports nested access: `src.foo.bar`
54 * - Must be rendered via `<CompositeComponent src={...} />`
55 */
56export function createCompositeFromStream(
57 stream: ReadableStream<Uint8Array>,
58 options?: {
59 slotUsagesStream?: ReadableStream<RscSlotUsageEvent>
60 } & StreamDecodeOptions,
61): AnyCompositeComponent {
62 const { getTree, streamWrapper, cssHrefs, jsPreloads } = setupStreamDecode(
63 stream,
64 options,
65 )
66β
67 return createRscProxy(getTree, {
68 stream: streamWrapper,
69 cssHrefs,
70 jsPreloads,
71 renderable: false,
72 slotUsagesStream: options?.slotUsagesStream,
73 })
74}
75β
76/**
77 * Shared stream decode setup for both renderable and composite.
78 */
79function setupStreamDecode(
80 stream: ReadableStream<Uint8Array>,
81 options?: StreamDecodeOptions,
82): {
83 getTree: () => unknown
84 streamWrapper: ServerComponentStream
85 cssHrefs: Set<string>
86 jsPreloads: Set<string> | undefined
87} {
88 const cssHrefs = new Set(options?.cssHrefs ?? [])
89 const jsPreloads = options?.jsPreloads
90 ? new Set(options.jsPreloads)
91 : undefined
92 const shouldDeferDecode = cssHrefs.size > 0 || !!jsPreloads?.size
93β
94 // Synchronous cache for the decoded tree.
95 let cachedTree: unknown = undefined
96 let cacheReady = false
97 let transformedTreePromise: Promise<unknown> | undefined
98β
99 const startDecode = () => {
100 if (!transformedTreePromise) {
101 // Promise for the tree with lazy elements awaited.
102 transformedTreePromise = Promise.resolve(browserDecode(stream)).then(
103 async (result) => {
104 await awaitLazyElements(result, (href) => {
105 cssHrefs.add(href)
106 })
107 cachedTree = unwrapRscCssEnvelope(result)
108 cacheReady = true
109 return cachedTree
110 },
111 )
112β
113 // Track the lazy element loading - prevents flash for RPC/RSC fetches.
114 trackPostProcessPromise(transformedTreePromise)
115 }
116β
117 return transformedTreePromise
118 }
119β
120 if (!shouldDeferDecode) {
121 // Start decoding eagerly during deserialization for non-SSR streams.
122 startDecode()
123 }
124β
125 const streamWrapper: ServerComponentStream = {
126 createReplayStream: () => stream,
127 }
128β
129 const getTree = () => {
130 if (cacheReady) return cachedTree
131 // eslint-disable-next-line react-hooks/rules-of-hooks
132 return use(startDecode())
133 }
134β
135 return { getTree, streamWrapper, cssHrefs, jsPreloads }
136}
137// Legacy export for backwards compatibility during migration
138export const createServerComponentFromStream = createCompositeFromStream