From 07124e4607c75ff1b7479a0001e237c683f045fe Mon Sep 17 00:00:00 2001 From: schiller-manuel <6340397+schiller-manuel@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:11:26 +0000 Subject: [PATCH 1/3] Initial plan From 20506baf76d9249879b35682458a441e0c0ca724 Mon Sep 17 00:00:00 2001 From: schiller-manuel <6340397+schiller-manuel@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:18:41 +0000 Subject: [PATCH 2/3] perf(react-start-rsc): lazy-load browser Flight decoder Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> --- .changeset/rsc-lazy-flight-client.md | 5 ++ .../react/guide/server-components.md | 4 ++ .../src/createServerComponentFromStream.ts | 23 ++++----- .../react-start-rsc/src/decodeRscStream.ts | 20 ++++++++ .../tests/ServerComponent.test.tsx | 3 ++ .../tests/lazyBrowserDecode.test.tsx | 51 +++++++++++++++++++ 6 files changed, 94 insertions(+), 12 deletions(-) create mode 100644 .changeset/rsc-lazy-flight-client.md create mode 100644 packages/react-start-rsc/src/decodeRscStream.ts create mode 100644 packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx 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..b80535e64c 100644 --- a/packages/react-start-rsc/src/createServerComponentFromStream.ts +++ b/packages/react-start-rsc/src/createServerComponentFromStream.ts @@ -2,11 +2,7 @@ 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 { AnyCompositeComponent, RscSlotUsageEvent, @@ -99,16 +95,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) => { + // 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. + transformedTreePromise = import('./decodeRscStream') + .then(({ decodeRscStream }) => + decodeRscStream(stream, (href) => { cssHrefs.add(href) - }) - cachedTree = unwrapRscCssEnvelope(result) + }), + ) + .then((tree) => { + cachedTree = tree cacheReady = true - return cachedTree - }, - ) + 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..2cd0b6ee7f --- /dev/null +++ b/packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx @@ -0,0 +1,51 @@ +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 })) + +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 + return { + createFromReadableStream: vi.fn(async () => + React.createElement('div', null, 'decoded'), + ), + } +}) + +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) + }) +}) From 8c9debdce1fac4c63f7ce85024aba66a0be9f15c Mon Sep 17 00:00:00 2001 From: schiller-manuel <6340397+schiller-manuel@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:42:55 +0000 Subject: [PATCH 3/3] perf(react-start-rsc): decode without import hop once the decoder is loaded Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> --- .../src/createServerComponentFromStream.ts | 31 +++++++++++++------ .../tests/lazyBrowserDecode.test.tsx | 27 ++++++++++++---- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/packages/react-start-rsc/src/createServerComponentFromStream.ts b/packages/react-start-rsc/src/createServerComponentFromStream.ts index b80535e64c..400dfe8647 100644 --- a/packages/react-start-rsc/src/createServerComponentFromStream.ts +++ b/packages/react-start-rsc/src/createServerComponentFromStream.ts @@ -3,12 +3,23 @@ import { use } from 'react' import { trackPostProcessPromise } from '@tanstack/start-client-core' import { createRscProxy } from './createRscProxy' +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 @@ -97,17 +108,17 @@ function setupStreamDecode( // Promise for the tree with lazy elements awaited. // 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. - transformedTreePromise = import('./decodeRscStream') - .then(({ decodeRscStream }) => - decodeRscStream(stream, (href) => { - cssHrefs.add(href) - }), - ) - .then((tree) => { - cachedTree = tree - cacheReady = true - return tree + 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/tests/lazyBrowserDecode.test.tsx b/packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx index 2cd0b6ee7f..575a3d9bee 100644 --- a/packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx +++ b/packages/react-start-rsc/tests/lazyBrowserDecode.test.tsx @@ -2,7 +2,10 @@ 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 })) +const decoder = vi.hoisted(() => ({ + loaded: false, + decode: vi.fn(), +})) vi.mock('@tanstack/start-client-core', () => ({ trackPostProcessPromise: vi.fn(), @@ -12,11 +15,10 @@ vi.mock('@tanstack/start-client-core', () => ({ // records whether the Flight client runtime has been pulled in. vi.mock('@vitejs/plugin-rsc/browser', () => { decoder.loaded = true - return { - createFromReadableStream: vi.fn(async () => - React.createElement('div', null, 'decoded'), - ), - } + decoder.decode.mockImplementation(async () => + React.createElement('div', null, 'decoded'), + ) + return { createFromReadableStream: decoder.decode } }) import { createCompositeFromStream } from '../src/createServerComponentFromStream' @@ -48,4 +50,17 @@ describe('browser Flight decoder 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) + }) })