fix: raw response handling #5276
main fromrefs/pull/5276/head·merged by schiller-manuel(GitHub profile, opens in a new tab) fixes #5271
fixes #5255
Summary by CodeRabbit#
New Features
- Server functions can return Response objects (sync or async); such Responses are marked with a new raw-response header so clients can receive them unchanged.
- Added a public constant to indicate raw responses.
Refactor
- Simplified exported fetcher/server-fn TypeScript generics and unified return typing.
- Explicitly typed start options and streamlined internal optional chaining for safer startup/serialization access.
Tests
- Expanded type tests for async/sync handlers returning Response, arrays, and unions.
- 1
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-server-core
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-client-core
View your CI Pipeline Execution ↗ for commit 126583684d6153a8c1174e13aff5567496939965
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 4m 45s View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 27s View ↗
☁️ Nx Cloud last updated this comment at
2025-09-30 21:59:18UTCMore templates
- tanstack-router-solid-example-basic
- tanstack-router-solid-example-basic-devtools-panel
- tanstack-router-solid-example-basic-file-based
- tanstack-router-solid-example-basic-non-nested-devtools
- tanstack-router-solid-example-basic-solid-query
- tanstack-router-solid-example-basic-solid-query-file-based
- tanstack-router-solid-example-basic-ssr-streaming-file-based
- tanstack-router-solid-example-kitchen-sink-file-based
- tanstack-router-solid-example-quickstart-file-based
- tanstack-solid-start-example-bare
- tanstack-solid-start-example-basic
- tanstack-solid-start-example-basic-static
- tanstack-router-react-example-authenticated-routes
- tanstack-router-react-example-authenticated-routes-firebase
- tanstack-router-react-example-basic
- tanstack-router-react-example-basic-default-search-params
- tanstack-router-react-example-basic-devtools-panel
- tanstack-router-react-example-basic-file-based
- tanstack-router-react-example-basic-non-nested-devtools
- tanstack-router-react-example-react-query
- tanstack-router-react-example-basic-react-query-file-based
- tanstack-router-react-example-basic-ssr-file-based
- tanstack-router-react-example-basic-ssr-streaming-file-based
- tanstack-router-react-example-basic-virtual-file-based
- tanstack-router-react-example-basic-virtual-inside-file-based
- tanstack-router-react-example-deferred-data
- tanstack-router-i18n-paraglide
- tanstack-router-react-example-kitchen-sink
- tanstack-router-react-example-kitchen-sink-file-based
- tanstack-router-react-example-kitchen-sink-react-query
- tanstack-router-react-example-kitchen-sink-react-query-file-based
- tanstack-router-react-example-large-file-based
- tanstack-router-react-example-location-masking
- tanstack-router-react-example-navigation-blocking
- tanstack-router-react-example-quickstart
- tanstack-router-react-example-quickstart-esbuild-file-based
- tanstack-router-react-example-quickstart-file-based
- tanstack-router-react-example-quickstart-rspack-file-based
- tanstack-router-react-example-quickstart-webpack-file-based
- router-monorepo-react-query
- router-mono-simple
- router-mono-simple-lazy
- tanstack-router-react-example-scroll-restoration
- tanstack-search-validator-adapters
- tanstack-start-example-bare
- tanstack-start-example-basic
- tanstack-start-example-basic-auth
- tanstack-start-example-basic-cloudflare
- tanstack-start-example-basic-react-query
- tanstack-start-example-basic-static
- tanstack-start-bun-hosting
- tanstack-start-example-convex-trellaux
- tanstack-start-example-counter
- tanstack-start-i18n-paraglide
- tanstack-start-example-large
- tanstack-start-example-material-ui
- tanstack-start-example-supabase-basic
- tanstack-start-tailwind-v4
- tanstack-start-example-trellaux
- tanstack-start-example-workos
- tanstack-router-react-example-view-transitions
- tanstack-router-react-example-with-framer-motion
- tanstack-router-react-example-with-trpc
- tanstack-router-react-example-with-trpc-react-query
@tanstack/arktype-adapter
npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5276@tanstack/directive-functions-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5276@tanstack/eslint-plugin-router
npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5276@tanstack/history
npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5276@tanstack/nitro-v2-vite-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5276@tanstack/react-router
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5276@tanstack/react-router-devtools
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5276@tanstack/react-router-ssr-query
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5276@tanstack/react-start
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5276@tanstack/react-start-client
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5276@tanstack/react-start-server
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5276@tanstack/router-cli
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5276@tanstack/router-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5276@tanstack/router-devtools
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5276@tanstack/router-devtools-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5276@tanstack/router-generator
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5276@tanstack/router-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5276@tanstack/router-ssr-query-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5276@tanstack/router-utils
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5276@tanstack/router-vite-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5276@tanstack/server-functions-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5276@tanstack/solid-router
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5276@tanstack/solid-router-devtools
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5276@tanstack/solid-start
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5276@tanstack/solid-start-client
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5276@tanstack/solid-start-server
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5276@tanstack/start-client-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5276@tanstack/start-plugin-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5276@tanstack/start-server-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5276@tanstack/start-static-server-functions
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5276@tanstack/start-storage-context
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5276@tanstack/valibot-adapter
npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5276@tanstack/virtual-file-routes
npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5276@tanstack/zod-adapter
npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5276commit:
1265836Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📥 Commits
Reviewing files that changed from the base of the PR and between 86b1dd9dac42f952f9d9f3f04ad7ef814298485d and 13b3ecf37d5f3d0639239e18b60c1218deb90e23.
📒 Files selected for processing (6)
packages/start-client-core/src/client-rpc/serverFnFetcher.ts(2 hunks)packages/start-client-core/src/constants.ts(1 hunks)packages/start-client-core/src/createServerFn.ts(1 hunks)packages/start-client-core/src/index.tsx(1 hunks)packages/start-client-core/src/tests/createServerFn.test-d.ts(2 hunks)packages/start-server-core/src/server-functions-handler.ts(2 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use TypeScript in strict mode with extensive type safety across the codebase
Files:
packages/start-client-core/src/createServerFn.tspackages/start-client-core/src/constants.tspackages/start-client-core/src/client-rpc/serverFnFetcher.tspackages/start-client-core/src/tests/createServerFn.test-d.tspackages/start-server-core/src/server-functions-handler.tspackages/start-client-core/src/index.tsx
packages/{*-start,start-*}/**
📄 CodeRabbit inference engine (AGENTS.md)
Name and place Start framework packages under packages/-start/ or packages/start-/
Files:
packages/start-client-core/src/createServerFn.tspackages/start-client-core/src/constants.tspackages/start-client-core/src/client-rpc/serverFnFetcher.tspackages/start-client-core/src/tests/createServerFn.test-d.tspackages/start-server-core/src/server-functions-handler.tspackages/start-client-core/src/index.tsx
🧬 Code graph analysis (4)
packages/start-client-core/src/constants.ts (1)
packages/start-client-core/src/index.tsx (1)
X_TSS_RAW_RESPONSE(88-88)
packages/start-client-core/src/client-rpc/serverFnFetcher.ts (2)
packages/start-client-core/src/constants.ts (1)
X_TSS_RAW_RESPONSE(8-8)
packages/start-client-core/src/index.tsx (1)
X_TSS_RAW_RESPONSE(88-88)
packages/start-client-core/src/tests/createServerFn.test-d.ts (1)
packages/start-client-core/src/createServerFn.ts (1)
createServerFn(51-170)
packages/start-server-core/src/server-functions-handler.ts (2)
packages/start-client-core/src/constants.ts (1)
X_TSS_RAW_RESPONSE(8-8)
packages/start-client-core/src/index.tsx (1)
X_TSS_RAW_RESPONSE(88-88)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Test
- GitHub Check: Preview
packages/start-server-core/src/server-functions-handler.ts lines 149 to 150@@ -145,4 +146,5 @@145146 // Any time we get a Response back, we should just146147 // return it immediately.147148 if (result.result instanceof Response) {149+ result.result.headers.set(X_TSS_RAW_RESPONSE, 'true')148150 return result.result⚠️ Potential issue | 🔴 Critical
Setting a header on an immutable Response will throw at runtime
When developers return a Response obtained from
fetch(very common for proxying upstream resources),response.headersis immutable. Callingseton it throwsTypeError: Headers guard is immutable, so this path will crash before the response ever reaches the client—precisely the scenario this PR is meant to fix. Instead of mutating the existing headers, clone them (and the response metadata) into a new Response that includesX_TSS_RAW_RESPONSE.Apply this diff to fix the issue:
- if (result.result instanceof Response) { - result.result.headers.set(X_TSS_RAW_RESPONSE, 'true') - return result.result - } + if (result.result instanceof Response) { + const rawResponse = result.result + const headers = new Headers(rawResponse.headers) + headers.set(X_TSS_RAW_RESPONSE, 'true') + return new Response(rawResponse.body, { + status: rawResponse.status, + statusText: rawResponse.statusText, + headers, + }) + }📝 Committable suggestion
‼️ IMPORTANT Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
if (result.result instanceof Response) { const rawResponse = result.result const headers = new Headers(rawResponse.headers) headers.set(X_TSS_RAW_RESPONSE, 'true') return new Response(rawResponse.body, { status: rawResponse.status, statusText: rawResponse.statusText, headers, }) }🤖 Prompt for AI Agents
In packages/start-server-core/src/server-functions-handler.ts around lines 149-150, the code attempts to call result.result.headers.set(...) on a Response returned from fetch, but fetch Responses have immutable headers and calling set throws at runtime; instead, create a new Response cloning the original body and metadata and use a mutable copy of the headers: construct a new Headers(result.result.headers), call set('X-TSS-RAW_RESPONSE','true') on that copy, then return new Response(result.result.body, { status: result.result.status, statusText: result.result.statusText, headers: headersCopy, /* copy any other relevant properties like duplex if used */ }); this avoids mutating the original immutable Headers and preserves the original response metadata and body.github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-client
Sign in to join this conversation.
Walkthrough#
Adds a raw-response pathway: introduces and exports
X_TSS_RAW_RESPONSE, server sets this header when returning aResponse, client fetcher short-circuits and returns the rawResponseimmediately, and server-function typings/tests updated to acceptResponseand various return shapes.Changes#
packages/start-client-core/src/constants.ts,packages/start-client-core/src/index.tsxX_TSS_RAW_RESPONSE = 'x-tss-raw'.packages/start-client-core/src/client-rpc/serverFnFetcher.tsX_TSS_RAW_RESPONSEand added early-return: if response headerx-tss-raw==='true', return the rawResponseimmediately, bypassing content-type processing and serialization.packages/start-client-core/src/createServerFn.ts,packages/start-client-core/src/tests/createServerFn.test-d.ts,packages/react-start-client/src/tests/createServerFn.test-d.tsxTRegisterfrom publicFetchergenerics; introduced newFetcherData<TResponse>mapping and adjustedServerFnReturnType/handler signatures; added/refined type tests for Response, arrays, and unions (sync/async).packages/start-server-core/src/server-functions-handler.tsX_TSS_RAW_RESPONSEand sets headerx-tss-raw: "true"onResponseresults so clients can detect raw responses.packages/start-client-core/src/getStartOptions.ts,packages/start-client-core/src/getDefaultSerovalPlugins.tsgetStartOptions; used optional chaining for readingstart.serializationAdaptersand adjusted related types.Sequence Diagram(s)#
Estimated code review effort#
🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs#
serverFnFetcherandserver-functions-handler; overlaps with runtime files changed here.createServerFn.ts.Suggested reviewers#
Poem#
Pre-merge checks and finishing touches#
❌ Failed checks (2 warnings)
@coderabbitai generate docstringsto improve docstring coverage.✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests
📜 Recent review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📥 Commits
Reviewing files that changed from the base of the PR and between 39f3e545ba8467dacf805ce6f30d8d7c77f16fd1 and 126583684d6153a8c1174e13aff5567496939965.
📒 Files selected for processing (3)
packages/start-client-core/src/createServerFn.ts(5 hunks)packages/start-client-core/src/getDefaultSerovalPlugins.ts(1 hunks)packages/start-client-core/src/getStartOptions.ts(1 hunks)🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Files:
packages/start-client-core/src/getStartOptions.tspackages/start-client-core/src/getDefaultSerovalPlugins.tspackages/start-client-core/src/createServerFn.tspackages/{*-start,start-*}/**
📄 CodeRabbit inference engine (AGENTS.md)
Files:
packages/start-client-core/src/getStartOptions.tspackages/start-client-core/src/getDefaultSerovalPlugins.tspackages/start-client-core/src/createServerFn.ts🧬 Code graph analysis (1)
packages/start-client-core/src/createServerFn.ts (3)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
🔇 Additional comments (7)
Comment `@coderabbitai help` to get the list of available commands and usage tips.