fix(start-server-core): deserialize tss context when using formdata

[empotts]

Fixes #5913 where the client TSS_CONTEXT is not deserialized when using formdata

Summary by CodeRabbit

• New Features

  • Added a FormData context test route with a UI to invoke two server actions and view results.

• Refactor

  • Improved server-side context deserialization for more reliable context handling (no public API changes).

• Tests

  • Added end-to-end tests verifying context propagation for FormData and simple server actions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Replaces ad-hoc JSON parsing of a serialized middleware context with seroval plugin-based deserialization in the server handler, and adds a new FormData-driven test route + UI and an e2e test that verifies client middleware context propagation when sending FormData.

Changes

Cohort / File(s)	Summary
Context deserialization refactor packages/start-server-core/src/server-functions-handler.ts	Replace JSON.parse + shallow merge with seroval.fromJSON (with plugins) to deserialize serializedContext into deserializedContext, then merge into params.context only if non-null. No public signature changes.
FormData test route & UI e2e/react-start/server-functions/src/routes/formdata-context.tsx	Add a new route component with client middleware that sends context, two server functions (formDataWithContextFn, simpleTestFn) that read middleware context, and UI controls to invoke and display results.
Route tree registration e2e/react-start/server-functions/src/routeTree.gen.ts	Register new FormdataContextRoute and wire it into all route mapping exports and TanStack Router module declarations.
End-to-end test e2e/react-start/server-functions/tests/server-functions.spec.ts	Add E2E test validating that client middleware context is delivered to server middleware when invoking a server function with FormData and when invoking a simple function. (Note: test block appears duplicated in the diff.)

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Browser
  participant ClientMiddleware
  participant Fetch(FormData)
  participant ServerHandler
  participant Seroval
  participant ServerMiddleware
  participant ServerFunction

  Browser->>ClientMiddleware: run client middleware -> sendContext(testString)
  ClientMiddleware->>Fetch(FormData): create FormData + attach serializedContext
  Fetch(FormData)->>ServerHandler: POST with FormData + serializedContext
  ServerHandler->>Seroval: fromJSON(serializedContext, plugins)
  Seroval-->>ServerHandler: deserializedContext
  ServerHandler->>ServerMiddleware: invoke with merged context
  ServerMiddleware->>ServerFunction: call function (context available)
  ServerFunction-->>Browser: JSON response (includes context/testString)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Verify seroval.fromJSON usage and plugin list match serialization encoding.
• Confirm conditional merge logic doesn't lose falsy-but-valid context values.
• Review new route typing/declaration additions and module augmentation.
• Inspect added e2e test for duplication and potential flakiness.

Possibly related PRs

• fix: undefined / null serialization #5501 — Modifies payload/context deserialization in server-functions-handler.ts; touches the same deserialization area.
• fix: memory leaks #5896 — Integrates serialization adapter wiring into start options/getRouter flow; related to server function serialization handling.
• fix: raw response handling #5276 — Also edits handleServerAction in server-functions-handler.ts (raw-response/header handling), overlapping the same handler surface.

Suggested reviewers

• schiller-manuel
• chorobin

Poem

🐰
I nibbled bytes and stitched a thread,
Seroval woke where JSON fled.
FormData carried my small song,
Middleware hummed — it wasn’t long.
Hops and tests — the fix is strong. 🎉

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title accurately describes the core fix: updating deserialization of TSS context for FormData requests in start-server-core.
Linked Issues check	✅ Passed	The PR fixes the linked issue #5913 by updating context deserialization in server-functions-handler.ts to use seroval plugins for proper FormData context handling.
Out of Scope Changes check	✅ Passed	Changes include the core fix in server-functions-handler.ts plus comprehensive e2e test coverage (new route, server functions, and test assertions), all aligned with resolving the FormData context issue.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 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 bbce531 and 72c6461.

📒 Files selected for processing (3)

• e2e/react-start/server-functions/src/routes/formdata-context.tsx (1 hunks)
• e2e/react-start/server-functions/tests/server-functions.spec.ts (1 hunks)
• packages/start-server-core/src/server-functions-handler.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/start-server-core/src/server-functions-handler.ts
• e2e/react-start/server-functions/src/routes/formdata-context.tsx
• e2e/react-start/server-functions/tests/server-functions.spec.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/start-server-core/src/server-functions-handler.ts (1)

95-95: Consider logging deserialization errors for debugging.

The empty catch block silently swallows errors during context deserialization. While this provides fail-safe behavior (falling back to the original context), adding a debug log would aid troubleshooting.

Apply this diff to add error logging:

-            } catch {}
+            } catch (error) {
+              console.debug('Failed to deserialize FormData context:', error)
+            }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bc79c97 and 128800a.

📒 Files selected for processing (1)

• packages/start-server-core/src/server-functions-handler.ts (1 hunks)

🔇 Additional comments (1)

packages/start-server-core/src/server-functions-handler.ts (1)

91-93: LGTM! Proper deserialization with seroval plugins.

The use of fromJSON with seroval plugins correctly deserializes the context, enabling support for complex types (Dates, Maps, Sets, etc.) that JSON.parse alone cannot handle. This brings the FormData context deserialization in line with the parsePayload function used elsewhere in the code.

[schiller-manuel]

thanks! we should also add a testcase to the e2e server functions test

[empotts]

thanks! we should also add a testcase to the e2e server functions test

Added a test similar to my reproducer and ran it. Seems to work along with the other tests.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 72c6461

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	7m 18s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	23s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-11-22 00:05:25 UTC

[empotts]

Anything else I need to add?

[pkg-pr-new]

More templates

• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• 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-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• 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-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• 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@5935

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5935

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5935

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5935

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5935

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5935

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5935

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5935

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5935

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5935

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5935

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5935

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5935

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5935

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5935

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5935

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5935

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5935

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5935

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5935

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5935

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5935

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5935

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@5935

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5935

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5935

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5935

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5935

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5935

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5935

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5935

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5935

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5935

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5935

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5935

commit: 72c6461