Streaming server functions return empty response body with @cloudflare/vite-plugin

[pdlug]

Which project does this relate to?

Start

Describe the bug

When using @cloudflare/vite-plugin with TanStack Start, streaming server functions (async generators) return empty response bodies in local development. The server executes correctly and yields values, response headers are correct, but the body is empty.

Your Example Website or App

code in example, needs cloudflare local

Steps to Reproduce the Bug or Issue

1. Create a TanStack Start project with @cloudflare/vite-plugin
2. Add a streaming server function using async generator
3. Run pnpm dev
4. Click the test button
5. Observe error: "Stream ended before first object"

vite.config.ts

import { cloudflare } from "@cloudflare/vite-plugin";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  server: { port: 3000 },
  plugins: [
    tanstackStart(),
    viteReact(),
    cloudflare({ viteEnvironment: { name: "ssr" } }),
  ],
});

src/routes/index.tsx

  import { createFileRoute } from "@tanstack/react-router";
  import { createServerFn } from "@tanstack/react-start";
  import { useState } from "react";

  const testStream = createServerFn().handler(async function* () {
    console.log("[server] Starting stream");
    yield { count: 1 };
    console.log("[server] Yielded 1");
    yield { count: 2 };
    console.log("[server] Yielded 2");
  });

  export const Route = createFileRoute("/")({
    component: Home,
  });

  function Home() {
    const [result, setResult] = useState("");

    const runTest = async () => {
      setResult("Starting...");
      try {
        for await (const item of await testStream()) {
          setResult((prev) => prev + ` ${item.count}`);
        }
        setResult((prev) => prev + " Done!");
      } catch (error) {
        setResult(`Error: ${error instanceof Error ? error.message : "Unknown"}`);
      }
    };

    return (
      <div>
        <button onClick={() => void runTest()}>Test Stream</button>
        <p>{result}</p>
      </div>
    );
  }

Expected behavior

The client should receive the yielded values { count: 1 } and { count: 2 }.

Actual behavior:

• Terminal shows server executing correctly:

  [server] Starting stream
  [server] Yielded 1
  [server] Yielded 2
  

• Client throws: Error: Stream ended before first object
• curl shows empty body:

  < HTTP/1.1 200 OK
  < content-type: application/x-ndjson
  < transfer-encoding: chunked
  < x-tss-serialized: true
  <
  * Connection #0 to host localhost left intact
  (empty body)
  

Screenshots or Videos

No response

Platform

• Router / Start Version: 1.140.0
• OS: macOS
• Browser: Chrome
• Browser Version: 144.0.0.0
• Bundler: Vite
• Bundler Version: 6.x
• Additional: @cloudflare/vite-plugin 1.17.0

Additional context

No response

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and agent prompts for this issue.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

🔗 Related PRs

#5363 - examples: Add a new TanStack Start example for typed readable streams [merged]
#5650 - fix: fix static server functions [merged]
#5837 - docs(solid-start): add start-streaming-data-from-server-functions example [merged]
#5847 - docs(solid-start): start-large example [merged]
#5910 - feat(start-plugin-core): vite preview support [merged]

👤 Suggested Assignees

• birkskyum
• fulopkovacs
• brenelz
• edmundhung

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

[schiller-manuel]

can you please provide the reproducer as a complete project in a git repo?

[coderabbitai]

Implementation Plan

Approach

Add Cloudflare Workers-specific handling for streaming server function responses in TanStack Start's dev server middleware to prevent ReadableStream bodies from being consumed or closed prematurely by h3 and srvx libraries.

Observations

TanStack Start uses Vite's multi-environment API with separate client and SSR environments. The dev server plugin registers middleware that handles server function requests by importing the server entry point via serverEnv.runner.import() and converting the Web Response to a Node.js response using sendNodeResponse() from the srvx/node library. Server functions create streaming responses with ReadableStream bodies that flow through h3's toResponse() for H3Event conversion before reaching sendNodeResponse. The framework currently has no runtime-specific response handling for different Vite environments.

Assumptions

Assumption 1: How to detect Cloudflare Workers environment

Options Considered:

• Check Vite environment configuration properties
• Inspect the runner instance type or properties
• Add explicit configuration flag for Cloudflare mode

Chosen Option: Check if the server environment uses a Cloudflare-specific runner by inspecting serverEnv.runner properties or the environment's configuration

Rationale: The Cloudflare plugin creates environments with specific characteristics that can be detected. This approach requires no user configuration changes and works automatically when the Cloudflare plugin is present.

Assumption 2: How to identify streaming responses that need special handling

Options Considered:

• Check for specific content-type headers (application/x-ndjson)
• Check for x-tss-serialized header
• Inspect Response body type (ReadableStream)
• Combination of content-type and serialization header

Chosen Option: Use a combination of x-tss-serialized: true header and application/x-ndjson content-type

Rationale: This precisely targets the problematic case without affecting other response types (HTML, JSON, raw Response objects). The existing codebase already uses these headers to mark streaming responses.

Assumption 3: How to stream the Response body to Node.js response

Options Considered:

• Use Node.js Streams API with response.body.pipeTo()
• Manually read chunks and write to Node.js response
• Use a Web Streams to Node.js Streams adapter library
• Convert ReadableStream to Node.js Readable stream

Chosen Option: Manually read chunks from the ReadableStream using a reader and write them to the Node.js response

Rationale: This approach avoids additional dependencies, gives full control over error handling and backpressure, works reliably with both Node.js and Cloudflare Workers environments, and follows standard Web Streams API patterns already used in the codebase.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Plan

Phase 1: Add Cloudflare Environment Detection

Extend the dev server middleware to detect when the Cloudflare Vite plugin's environment runner is active, enabling Cloudflare-specific response handling paths.

Task 1: Add Cloudflare Environment Detection Function

Create a utility function to detect if the current server environment is using the Cloudflare Workers runtime.

• Add a helper function in packages/start-plugin-core/src/dev-server-plugin/plugin.ts that checks if the server environment runner indicates Cloudflare Workers
• Inspect the environment's configuration or runner properties to identify Cloudflare-specific characteristics
• Return a boolean indicating whether Cloudflare-specific handling should be applied

Task 2: Add Streaming Response Detection Function

Create a utility function to identify streaming server function responses that need special handling.

• Add a helper function in packages/start-plugin-core/src/dev-server-plugin/plugin.ts that examines Response headers
• Check for both x-tss-serialized: true header and content-type: application/x-ndjson header
• Return a boolean indicating whether the response is a streaming server function response

🤖 Prompt for AI agents

Add detection utilities for Cloudflare environment and streaming responses.

In `packages/start-plugin-core/src/dev-server-plugin/plugin.ts`:
- Create a helper function to detect Cloudflare Workers environment by
inspecting serverEnv.runner properties or environment configuration
- Create a helper function to detect streaming responses by checking for
x-tss-serialized: true header AND content-type: application/x-ndjson header
- Both functions should return boolean values

Phase 2: Implement Alternative Response Handling Path

Modify the dev server middleware to use a custom streaming response handler when both Cloudflare environment and streaming response are detected, bypassing sendNodeResponse.

Task 1: Create Custom Stream Handler for Cloudflare

Implement a function that manually transfers ReadableStream body chunks to the Node.js response.

• Add a new function in packages/start-plugin-core/src/dev-server-plugin/plugin.ts that accepts a Node.js response and Web Response object
• Copy status code, status text, and headers from Web Response to Node.js response (excluding problematic headers)
• Handle set-cookie headers properly by splitting multi-value headers
• Get a reader from the ReadableStream body and read chunks in a loop
• Write each chunk directly to the Node.js response
• Handle stream completion by calling res.end()

Task 2: Add Conditional Response Handling Logic

Modify the middleware to choose between the custom handler and sendNodeResponse based on environment and response type.

• Update the middleware handler in packages/start-plugin-core/src/dev-server-plugin/plugin.ts after the serverEntry['default'].fetch(webReq) call
• Check if Cloudflare environment is active using the detection function from Task 1.1
• Check if the response is a streaming response using the detection function from Task 1.2
• If both conditions are true, call the custom stream handler from Task 2.1
• Otherwise, use the existing sendNodeResponse() path
• Ensure the conditional logic is applied before any response body is consumed

🤖 Prompt for AI agents

Implement custom streaming handler and integrate it into the middleware.

In `packages/start-plugin-core/src/dev-server-plugin/plugin.ts`:
- Create a function that accepts Node.js response and Web Response objects
- Copy status code, status text, and headers from Web Response to Node.js
response (handle set-cookie properly)
- Use ReadableStream reader to read chunks in a loop and write directly to
Node.js response
- Call res.end() when stream completes
- Update middleware handler after serverEntry['default'].fetch(webReq) call
- Add conditional logic: if Cloudflare environment AND streaming response, use
custom handler; otherwise use sendNodeResponse()
- Ensure logic runs before response body is consumed

Phase 3: Update Error Handling and Edge Cases

Ensure the custom streaming path handles errors, stream cancellation, and edge cases gracefully.

Task 1: Add Stream Error Handling

Implement error handling for the custom streaming path to catch and properly handle stream failures.

• Add try-catch blocks around the stream reading loop in the custom handler from Task 2.1
• Handle ReadableStream errors by logging the error and ending the Node.js response with an error status if headers haven't been sent
• Handle client disconnection (Node.js response events) by canceling the ReadableStream reader
• Ensure cleanup occurs in all error scenarios to prevent resource leaks

Task 2: Update Existing Error Responses

Ensure JSON and HTML error responses in the middleware continue to work correctly and don't trigger the Cloudflare-specific path.

• Review the existing error response handling in packages/start-plugin-core/src/dev-server-plugin/plugin.ts
• Verify that error responses (JSON and HTML) skip the Cloudflare detection logic since they're not streaming responses
• Ensure the streaming response detection function correctly returns false for error responses
• No changes should be needed if the detection function properly checks for both required headers

🤖 Prompt for AI agents

Add comprehensive error handling to the custom streaming path.

In `packages/start-plugin-core/src/dev-server-plugin/plugin.ts`:
- Add try-catch blocks around the stream reading loop in the custom handler
- Handle ReadableStream errors by logging and ending response with error status
if headers not sent
- Handle client disconnection by canceling the ReadableStream reader
- Ensure cleanup in all error scenarios
- Verify existing error responses (JSON/HTML) skip Cloudflare-specific path
- Confirm streaming detection function returns false for error responses

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Add detection utilities for Cloudflare environment and streaming responses.

In `packages/start-plugin-core/src/dev-server-plugin/plugin.ts`:
- Create a helper function to detect Cloudflare Workers environment by
inspecting serverEnv.runner properties or environment configuration
- Create a helper function to detect streaming responses by checking for
x-tss-serialized: true header AND content-type: application/x-ndjson header
- Both functions should return boolean values
===============================================================================

Task: 2

Implement custom streaming handler and integrate it into the middleware.

In `packages/start-plugin-core/src/dev-server-plugin/plugin.ts`:
- Create a function that accepts Node.js response and Web Response objects
- Copy status code, status text, and headers from Web Response to Node.js
response (handle set-cookie properly)
- Use ReadableStream reader to read chunks in a loop and write directly to
Node.js response
- Call res.end() when stream completes
- Update middleware handler after serverEntry['default'].fetch(webReq) call
- Add conditional logic: if Cloudflare environment AND streaming response, use
custom handler; otherwise use sendNodeResponse()
- Ensure logic runs before response body is consumed
===============================================================================

Task: 3

Add comprehensive error handling to the custom streaming path.

In `packages/start-plugin-core/src/dev-server-plugin/plugin.ts`:
- Add try-catch blocks around the stream reading loop in the custom handler
- Handle ReadableStream errors by logging and ending response with error status
if headers not sent
- Handle client disconnection by canceling the ReadableStream reader
- Ensure cleanup in all error scenarios
- Verify existing error responses (JSON/HTML) skip Cloudflare-specific path
- Confirm streaming detection function returns false for error responses

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

[pdlug]

@schiller-manuel here's a repo: https://github.com/pdlug/tanstack-cf-workers-streaming