Start: Support Buf-Connect Message types as return values from ServerFn

[frenzzy]

Description
When using TanStack Start’s React example together with a Buf Connect client (from the official Connect-ES examples), a ServerFn handler that simply returns the Protobuf message instance is rejected by TypeScript’s typing because it includes internal fields like $unknown and binary data (Uint8Array/ArrayBuffer). In practice these message objects are fully structured-cloneable, but the current ServerFn generic is too strict and treats them as non-serializable.

Reproduction

1. Clone and set up the official examples:

   git clone https://github.com/TanStack/router.git
   cd router/examples/react
   npm install

2. Install Buf Connect packages:

   npm install @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf

3. In src/server.ts add a simple RPC route that returns the raw message from Connect:

   // src/server.ts
   import { router, ServerFnCtx } from '@tanstack/start/router'
   import { createPromiseClient } from '@connectrpc/connect'
   import { createConnectTransport } from '@connectrpc/connect-node'
   import { EchoService } from '@connectrpc/examples-es/gen/echo/v1/echo_pb.js'
   import { EchoRequest, EchoResponse } from '@connectrpc/examples-es/gen/echo/v1/echo_pb.js'
   
   const transport = createConnectTransport({ baseUrl: 'http://localhost:8080' })
   const client = createPromiseClient(EchoService, transport)
   
   export const appRouter = router()
     .route({
       path: '/echo',
       response: EchoResponse, // using the generated Message type as response schema
     })
     .handler(async (ctx: ServerFnCtx<'GET', 'echo'>) => {
       // This line fails TS2345 because EchoResponse has `$unknown?: UnknownField[]` and Uint8Array
       return await client.echo(new EchoRequest({ message: 'hello' }))
     })

4. Observe the error:

   Argument of type 'Promise<EchoResponse>' is not assignable to parameter of type 'ServerFn<..., EchoResponse>'
   Type 'EchoResponse' is not serializable: 
     Property '$unknown' is typed as UnknownField[] (with Uint8Array data and ArrayBuffer methods),
     which does not satisfy the Router’s JSON-serializable constraints.

Versions

• @tanstack/react-start: 1.128.3
• @tanstack/react-router: 1.128.3
• @connectrpc/connect: 2.0.2
• @connectrpc/connect-node: 2.0.2
• @bufbuild/protobuf: 2.6.1
• typescript: 5.8.3

Expected Behavior
ServerFn handlers should be allowed to return any structured-cloneable value, including Buf-Connect message instances containing binary fields (Uint8Array, ArrayBuffer) or optional $unknown arrays. Under the hood, React Server Components (and TanStack Server Functions) use structured cloning, which supports these types.

Suggested Fixes

• Loosen the ServerFn return-type constraint to accept any object that passes structured-cloning rules (not just pure JSON).

• Provide a way to explicitly mark a return type as “bypass strict JSON check”, so advanced use-cases (e.g. Protobuf) work out of the box.

• (Optional) Add built-in support for Buf-Connect messages by recognizing MessageShape<T> and treating them as serializable.

[schiller-manuel]

what do you mean about "React Server Components" here?
also ,where do we use structuredClone() ?

i also don't see createServerFn() being used in your example.

can you please provide a complete example repo?

[frenzzy]

Please see src/routes/index.tsx in: https://codesandbox.io/p/devbox/sweet-morning-4j3csk?workspaceId=ws_6dqdrTHLVynDrfLQZJbocJ

Argument of type '() => Promise<SayResponse>' is not assignable to parameter of type 'ServerFn<Method, "data", undefined, undefined, SayResponse>'.
  Type 'Promise<SayResponse>' is not assignable to type 'Promise<{ readonly $typeName: "connectrpc.eliza.v1.SayResponse"; $unknown?: { readonly no: number; readonly wireType: WireType; readonly data: { [x: number]: number; readonly BYTES_PER_ELEMENT: number; ... 32 more ...; readonly [Symbol.toStringTag]: "Uint8Array"; }; }[] | undefined; sentence: string; }> | { ...; }'.
    Type 'Promise<SayResponse>' is not assignable to type 'Promise<{ readonly $typeName: "connectrpc.eliza.v1.SayResponse"; $unknown?: { readonly no: number; readonly wireType: WireType; readonly data: { [x: number]: number; readonly BYTES_PER_ELEMENT: number; ... 32 more ...; readonly [Symbol.toStringTag]: "Uint8Array"; }; }[] | undefined; sentence: string; }>'.
      Type 'SayResponse' is not assignable to type '{ readonly $typeName: "connectrpc.eliza.v1.SayResponse"; $unknown?: { readonly no: number; readonly wireType: WireType; readonly data: { [x: number]: number; readonly BYTES_PER_ELEMENT: number; ... 32 more ...; readonly [Symbol.toStringTag]: "Uint8Array"; }; }[] | undefined; sentence: string; }'.
        Types of property '$unknown' are incompatible.
          Type 'UnknownField[] | undefined' is not assignable to type '{ readonly no: number; readonly wireType: WireType; readonly data: { [x: number]: number; readonly BYTES_PER_ELEMENT: number; readonly buffer: { readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.toStringTag]: string; } | { ...; }; ... 31 more ...; readonly [Symbol.toStringTag]: "Ui...'.
            Type 'UnknownField[]' is not assignable to type '{ readonly no: number; readonly wireType: WireType; readonly data: { [x: number]: number; readonly BYTES_PER_ELEMENT: number; readonly buffer: { readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.toStringTag]: string; } | { ...; }; ... 31 more ...; readonly [Symbol.toStringTag]: "Ui...'.
              Type 'UnknownField' is not assignable to type '{ readonly no: number; readonly wireType: WireType; readonly data: { [x: number]: number; readonly BYTES_PER_ELEMENT: number; readonly buffer: { readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.toStringTag]: string; } | { ...; }; ... 31 more ...; readonly [Symbol.toStringTag]: "Ui...'.
                The types of 'data.buffer' are incompatible between these types.
                  Type 'ArrayBufferLike' is not assignable to type '{ readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.toStringTag]: string; } | { readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.species]: ...; readonly [Symbol.toStringTag]: "SharedArrayBuffer"; }'.
                    Type 'ArrayBuffer' is not assignable to type '{ readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.toStringTag]: string; } | { readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.species]: ...; readonly [Symbol.toStringTag]: "SharedArrayBuffer"; }'.
                      Type 'ArrayBuffer' is not assignable to type '{ readonly byteLength: number; slice: "Function is not serializable"; readonly [Symbol.toStringTag]: string; }'.
                        Types of property 'slice' are incompatible.
                          Type '(begin: number, end?: number | undefined) => ArrayBuffer' is not assignable to type '"Function is not serializable"'.ts(2345)