Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

createCompositeComponent.ts

341 lines9.2 KB

1import { createElement } from 'react'
2import { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'
3import { getStartContext } from '@tanstack/start-storage-context'
4import { sanitizeSlotArgs } from './slotUsageSanitizer'
5import { ReplayableStream } from './ReplayableStream'
6import { ClientSlot } from './ClientSlot'
7import {
8 RSC_SLOT_USAGES_STREAM,
9 SERVER_COMPONENT_STREAM,
10} from './ServerComponentTypes'
11import { createRscCssEnvelope } from './rscCssEnvelope'
12import type {
13 AnyCompositeComponent,
14 CompositeComponentResult,
15 RscSlotUsageEvent,
16 ServerComponentStream,
17 ValidateCompositeComponent,
18} from './ServerComponentTypes'
19import type { RscCssEnvelopeOptions } from './rscCssEnvelope'
20​
21import './rscSsrHandler' // Import for global declaration side effect
22​
23/**
24 * Creates a composite server component with slot support.
25 *
26 * Supports returning:
27 * - A ReactNode directly
28 * - An object structure with ReactNodes: accessed as `src.Foo`
29 * - Nested structures: accessed as `src.x.Bar`
30 *
31 * Props that are functions become slots - they render as ClientSlot placeholders
32 * in the RSC output, filled in by the consumer with actual implementations.
33 *
34 * The returned value is NOT directly renderable. Use `<CompositeComponent src={...} />`.
35 *
36 * @example
37 * ```tsx
38 * const src = await createCompositeComponent((props) => (
39 * <div>
40 * <header>{props.header('Dashboard')}</header>
41 * <main>{props.children}</main>
42 * </div>
43 * ))
44 *
45 * // In route component
46 * return (
47 * <CompositeComponent src={src} header={(title) => <h1>{title}</h1>}>
48 * <p>Main content</p>
49 * </CompositeComponent>
50 * )
51 * ```
52 */
53export async function createCompositeComponent<TComp>(
54 component: ValidateCompositeComponent<TComp>,
55 options?: RscCssEnvelopeOptions,
56): Promise<CompositeComponentResult<TComp>> {
57 const isDev = process.env.NODE_ENV === 'development'
58​
59 // Dev-only: stream slot usage events (slot + raw args)
60 const slotUsagesEmitter = isDev
61 ? createReadableStreamEmitter<RscSlotUsageEvent>()
62 : null
63​
64 // Create a wrapper component that will be rendered inside React's Flight context.
65 // This ensures React.cache works properly since the component is called during
66 // renderToReadableStream's render phase, not before it.
67 const { proxy: proxyProps } = createSlotProxy<{}>({
68 onSlotCall: slotUsagesEmitter
69 ? (name, args) => {
70 const sanitizedArgs = sanitizeSlotArgs(args)
71 slotUsagesEmitter.emit({
72 slot: name,
73 args: sanitizedArgs.length ? sanitizedArgs : undefined,
74 })
75 }
76 : undefined,
77 })
78​
79 // Wrapper that renders the user's component inside Flight render context
80 async function ServerComponentWrapper() {
81 return createRscCssEnvelope(
82 await (component as React.FC)(proxyProps),
83 options,
84 )
85 }
86​
87 // Render using createElement so React calls our component during Flight rendering
88 // This is critical for React.cache to work - the component must be invoked
89 // during renderToReadableStream's execution, not before
90 const flightStream = renderToReadableStream(
91 createElement(ServerComponentWrapper as any),
92 )
93​
94 // Check if this is an SSR request (router) or a direct server function call
95 const ctx = getStartContext({ throwIfNotFound: false })
96 const isRouterRequest = ctx?.handlerType === 'router'
97 const ssrHandler = globalThis.__RSC_SSR__
98​
99 // SSR path: buffer stream for replay, pre-decode for synchronous rendering
100 if (isRouterRequest && ssrHandler) {
101 const signal = ctx.request.signal
102 const stream = new ReplayableStream(flightStream, { signal })
103​
104 // Pre-decode during loader phase for synchronous SSR rendering
105 const decoded = await ssrHandler.decode(stream)
106​
107 // For SSR we know decode fully consumed the Flight stream.
108 slotUsagesEmitter?.close()
109​
110 return ssrHandler.createCompositeProxy(
111 stream,
112 decoded,
113 slotUsagesEmitter?.stream,
114 ) as CompositeComponentResult<TComp>
115 }
116​
117 // Server function call path:
118 // The serialization adapter will stream to the client.
119 const monitoredFlightStream =
120 isDev && slotUsagesEmitter
121 ? wrapReadableStream(flightStream, {
122 onDone: () => {
123 slotUsagesEmitter.close()
124 },
125 onCancel: () => {
126 slotUsagesEmitter.close()
127 },
128 onError: () => {
129 slotUsagesEmitter.close()
130 },
131 })
132 : flightStream
133​
134 return createCompositeHandle(monitoredFlightStream, {
135 slotUsagesStream: slotUsagesEmitter?.stream,
136 }) as CompositeComponentResult<TComp>
138​
139/**
140 * Creates a composite handle for server function responses.
141 * No proxy needed - the client will decode and create its own proxy.
142 */
143function createCompositeHandle(
144 flightStream: ReadableStream<Uint8Array>,
145 options?: {
146 slotUsagesStream?: ReadableStream<RscSlotUsageEvent>
147 },
148): AnyCompositeComponent {
149 // Simple single-use stream wrapper. For server function calls, the stream
150 // is consumed exactly once by the serialization adapter for transport.
151 const streamWrapper: ServerComponentStream = {
152 createReplayStream: () => flightStream,
153 }
154​
155 // Create a stub function with the stream attached for serialization.
156 // This will never be rendered directly - it goes through serialization
157 // which extracts the stream and sends it to the client.
158 const stub = function CompositeComponentStub(): never {
159 throw new Error(
160 'CompositeComponent from server function cannot be rendered on server. ' +
161 'It should be serialized and sent to the client.',
162 )
163 }
164​
165 ;(stub as any)[SERVER_COMPONENT_STREAM] = streamWrapper
166 // Note: RENDERABLE_RSC is not set (or implicitly false), indicating this is a composite component
167​
168 if (options?.slotUsagesStream) {
169 ;(stub as any)[RSC_SLOT_USAGES_STREAM] = options.slotUsagesStream
170 }
171​
172 return stub as unknown as AnyCompositeComponent
174​
175/**
176 * Base slot props type - functions that become ClientSlot placeholders
177 */
178interface SlotPropsBase {
179 [key: string]:
180 | ((...args: Array<any>) => React.ReactNode)
181 | React.ReactNode
182 | undefined
183 children?: React.ReactNode
185​
186interface SlotProxyResult<TSlotProps extends object> {
187 proxy: TSlotProps & SlotPropsBase
189​
190/**
191 * Proxy that turns property access into ClientSlot renders.
192 * Also tracks accessed slot names for devtools.
193 */
194function createSlotProxy<TSlotProps extends object>(options?: {
195 onSlotCall?: (name: string, args: Array<any>) => void
196}): SlotProxyResult<TSlotProps> {
197 const cache = new Map<string, (...args: Array<any>) => React.ReactNode>()
198​
199 const proxy = new Proxy({} as TSlotProps & SlotPropsBase, {
200 get(_target, prop) {
201 if (prop === 'then' || typeof prop !== 'string') return undefined
202​
203 if (prop === 'children') {
204 options?.onSlotCall?.('children', [])
205 return createElement(ClientSlot, { slot: 'children', args: [] })
206 }
207​
208 let fn = cache.get(prop)
209 if (!fn) {
210 fn = (...args: Array<any>) => {
211 options?.onSlotCall?.(prop, args)
212 return createElement(ClientSlot, { slot: prop, args })
213 }
214 cache.set(prop, fn)
215 }
216 return fn
217 },
218 })
219​
220 return {
221 proxy,
222 }
224​
225function createReadableStreamEmitter<T>(): {
226 stream: ReadableStream<T>
227 emit: (value: T) => void
228 close: () => void
229} {
230 let closed = false
231 const queue: Array<T> = []
232 let controller: ReadableStreamDefaultController<T> | null = null
233​
234 const stream = new ReadableStream<T>({
235 start(ctrl) {
236 controller = ctrl
237 for (const value of queue) {
238 try {
239 ctrl.enqueue(value)
240 } catch {
241 // Ignore
242 }
243 }
244 queue.length = 0
245 if (closed) {
246 try {
247 ctrl.close()
248 } catch {
249 // Ignore
250 }
251 }
252 },
253 cancel() {
254 closed = true
255 controller = null
256 queue.length = 0
257 },
258 })
259​
260 const emit = (value: T) => {
261 if (closed) return
262 if (!controller) {
263 queue.push(value)
264 return
265 }
266 try {
267 controller.enqueue(value)
268 } catch {
269 // Ignore
270 }
271 }
272​
273 const close = () => {
274 if (closed) return
275 closed = true
276 if (controller) {
277 try {
278 controller.close()
279 } catch {
280 // Ignore
281 }
282 controller = null
283 }
284 }
285​
286 return { stream, emit, close }
288​
289function wrapReadableStream<T>(
290 source: ReadableStream<T>,
291 handlers: {
292 onDone?: () => void
293 onCancel?: () => void
294 onError?: () => void
295 },
296): ReadableStream<T> {
297 const reader = source.getReader()
298 let finished = false
299​
300 const finish = () => {
301 if (finished) return
302 finished = true
303 handlers.onDone?.()
304 try {
305 reader.releaseLock()
306 } catch {
307 // Ignore
308 }
309 }
310​
311 return new ReadableStream<T>({
312 async pull(controller) {
313 try {
314 const { value, done } = await reader.read()
315 if (done) {
316 controller.close()
317 finish()
318 return
319 }
320 controller.enqueue(value)
321 } catch (err) {
322 try {
323 controller.error(err)
324 } catch {
325 // Ignore
326 }
327 handlers.onError?.()
328 finish()
329 }
330 },
331 async cancel(reason) {
332 handlers.onCancel?.()
333 try {
334 await reader.cancel(reason)
335 } catch {
336 // Ignore
337 }
338 finish()
339 },
340 })