diff --git a/.changeset/rsc-lazy-flight-client.md b/.changeset/rsc-lazy-flight-client.md new file mode 100644 index 0000000000..900c784e32 --- /dev/null +++ b/.changeset/rsc-lazy-flight-client.md @@ -0,0 +1,5 @@ +--- +'@tanstack/react-start-rsc': patch +--- + +Load the browser Flight client runtime (`react-server-dom` client plus lazy-element/CSS post-processing) on first server component decode instead of bundling it into the client entry chunk. Enabling RSC no longer adds ~20 kB raw / ~6.4 kB gzip to the entry chunk of every route; only routes that decode a server component fetch it. diff --git a/docs/start/framework/react/guide/server-components.md b/docs/start/framework/react/guide/server-components.md index 581ae145bd..4e17709546 100644 --- a/docs/start/framework/react/guide/server-components.md +++ b/docs/start/framework/react/guide/server-components.md @@ -1079,6 +1079,10 @@ When a server component accesses slot props, it accesses a proxy: TanStack Start sends a React Flight stream with these placeholders. On the client, placeholders are replaced with the actual props you passed when rendering. +### Client Bundle Cost + +Enabling RSC adds a small serialization adapter to the client entry chunk so any server function response can carry a server component. The browser Flight decoder (`react-server-dom`'s client runtime) is loaded in a separate chunk the first time a server component is decoded, so routes that never render one don't download it. + ## Current Status Server Components are experimental in TanStack Start and will remain so into early v1. diff --git a/packages/react-start-rsc/src/createServerComponentFromStream.ts b/packages/react-start-rsc/src/createServerComponentFromStream.ts index 2616b96f44..400dfe8647 100644 --- a/packages/react-start-rsc/src/createServerComponentFromStream.ts +++ b/packages/react-start-rsc/src/createServerComponentFromStream.ts @@ -2,17 +2,24 @@ import { use } from 'react' import { trackPostProcessPromise } from '@tanstack/start-client-core' -import { createFromReadableStream as browserDecode } from 'virtual:tanstack-rsc-browser-decode' - -import { awaitLazyElements } from './awaitLazyElements' import { createRscProxy } from './createRscProxy' -import { unwrapRscCssEnvelope } from './rscCssEnvelope' +import type { decodeRscStream } from './decodeRscStream' import type { AnyCompositeComponent, RscSlotUsageEvent, ServerComponentStream, } from './ServerComponentTypes' +type DecoderModule = { decodeRscStream: typeof decodeRscStream } + +// Once loaded, decode without another `import()` hop: a resolved dynamic +// import still settles in a later task, which would let React show Suspense +// fallbacks for streams that previously decoded within the same task. +let decoderModule: DecoderModule | undefined + +const loadDecoderModule = () => + import('./decodeRscStream').then((mod) => (decoderModule = mod)) + type StreamDecodeOptions = { cssHrefs?: Iterable jsPreloads?: Iterable @@ -99,16 +106,19 @@ function setupStreamDecode( const startDecode = () => { if (!transformedTreePromise) { // Promise for the tree with lazy elements awaited. - transformedTreePromise = Promise.resolve(browserDecode(stream)).then( - async (result) => { - await awaitLazyElements(result, (href) => { - cssHrefs.add(href) - }) - cachedTree = unwrapRscCssEnvelope(result) - cacheReady = true - return cachedTree - }, - ) + // The Flight client runtime is imported on first decode so it stays out + // of the entry chunk for routes that never render a server component. + const decode = ({ decodeRscStream }: DecoderModule) => + decodeRscStream(stream, (href) => { + cssHrefs.add(href) + }) + transformedTreePromise = ( + decoderModule ? decode(decoderModule) : loadDecoderModule().then(decode) + ).then((tree) => { + cachedTree = tree + cacheReady = true + return tree + }) // Track the lazy element loading - prevents flash for RPC/RSC fetches. trackPostProcessPromise(transformedTreePromise) diff --git a/packages/react-start-rsc/src/decodeRscStream.ts b/packages/react-start-rsc/src/decodeRscStream.ts new file mode 100644 index 0000000000..70e1abca9c --- /dev/null +++ b/packages/react-start-rsc/src/decodeRscStream.ts @@ -0,0 +1,20 @@ +import { createFromReadableStream } from 'virtual:tanstack-rsc-browser-decode' +import { awaitLazyElements } from './awaitLazyElements' +import { unwrapRscCssEnvelope } from './rscCssEnvelope' +import type { CssHrefCollector } from './awaitLazyElements' + +/** + * Decodes a Flight stream in the browser and waits for its lazy elements. + * + * Loaded on demand by `createServerComponentFromStream` so the Flight client + * runtime is only fetched once a server component is actually decoded, + * instead of shipping in the entry chunk of every RSC-enabled app. + */ +export async function decodeRscStream( + stream: ReadableStream, + cssCollector: CssHrefCollector, +): Promise { + const result = await createFromReadableStream(stream) + await awaitLazyElements(result, cssCollector) + return unwrapRscCssEnvelope(result) +} diff --git a/packages/react-start-rsc/tests/ServerComponent.test.tsx b/packages/react-start-rsc/tests/ServerComponent.test.tsx index 8c39d1dfe8..c831ca929f 100644 --- a/packages/react-start-rsc/tests/ServerComponent.test.tsx +++ b/packages/react-start-rsc/tests/ServerComponent.test.tsx @@ -83,6 +83,9 @@ describe('ServerComponent (client)', () => { await Promise.resolve() }) + // The decoder is imported lazily, so wait for the first decode call. + await vi.waitFor(() => expect(decodeMock).toHaveBeenCalled()) + // Should only decode once even though we render twice expect(decodeMock).toHaveBeenCalledTimes(1) expect(createdReadableStream).toBeDefined() diff --git a/packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx b/packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx new file mode 100644 index 0000000000..575a3d9bee --- /dev/null +++ b/packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx @@ -0,0 +1,66 @@ +import React from 'react' +import { describe, expect, it, vi } from 'vitest' +import { act, render, screen } from '@testing-library/react' + +const decoder = vi.hoisted(() => ({ + loaded: false, + decode: vi.fn(), +})) + +vi.mock('@tanstack/start-client-core', () => ({ + trackPostProcessPromise: vi.fn(), +})) + +// The factory runs when the decoder module is first imported, so `loaded` +// records whether the Flight client runtime has been pulled in. +vi.mock('@vitejs/plugin-rsc/browser', () => { + decoder.loaded = true + decoder.decode.mockImplementation(async () => + React.createElement('div', null, 'decoded'), + ) + return { createFromReadableStream: decoder.decode } +}) + +import { createCompositeFromStream } from '../src/createServerComponentFromStream' +import { CompositeComponent } from '../src/CompositeComponent' + +describe('browser Flight decoder loading', () => { + it('loads the decoder only when a stream is decoded', async () => { + const stream = new ReadableStream({ + start(controller) { + controller.close() + }, + }) + + // Deferred decode: SSR asset deps keep decoding until first render. + const src = createCompositeFromStream(stream, { + cssHrefs: ['/assets/component.css'], + }) + + expect(decoder.loaded).toBe(false) + + await act(async () => { + render( + loading}> + + , + ) + }) + + expect(await screen.findByText('decoded')).toBeTruthy() + expect(decoder.loaded).toBe(true) + }) + + it('decodes synchronously once the decoder is loaded', () => { + // Relies on the previous test having loaded the decoder. + expect(decoder.loaded).toBe(true) + decoder.decode.mockClear() + + const stream = new ReadableStream() + createCompositeFromStream(stream) + + // Starting decode in the same task avoids Suspense fallbacks for streamed + // server components that previously decoded without an extra task hop. + expect(decoder.decode).toHaveBeenCalledWith(stream) + }) +})