feat: allow custom fetch impl for server functions

[schiller-manuel]

Summary by CodeRabbit

• New Features

  • Per-call custom fetch support for server functions and middleware, with call-site override precedence and a new exported CustomFetch type.

• UI

  • Demo page showcasing custom-fetch scenarios with interactive verification tests.
  • Added navigation link to the custom-fetch demo from the home route.

• Tests

  • Added end-to-end tests for direct, middleware, chained, override, and default-fetch behaviors.

• Documentation

  • Expanded middleware guide with header merging, fetch precedence, and examples.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds per-call CustomFetch propagation through client RPC, middleware, and server-function layers; introduces a new /custom-fetch file route with component, server functions and middleware, E2E tests, generated route-tree updates, public type exports, and expanded docs on fetch/header precedence.

Changes

Cohort / File(s)	Summary
Route Tree Generation e2e/react-start/server-functions/src/routeTree.gen.ts	Adds CustomFetchRoute (/custom-fetch) into generated route tree and exposes it in RootRouteChildren and FileRoutes maps.
New Route Implementation e2e/react-start/server-functions/src/routes/custom-fetch.tsx, e2e/react-start/server-functions/src/routes/index.tsx	New /custom-fetch file route: component, server functions, and middleware demonstrating custom-fetch precedence; adds nav link.
E2E Tests e2e/react-start/server-functions/tests/server-functions.spec.ts	Adds five Playwright tests for call-site fetch, middleware fetch, chained middleware precedence, direct override, and default fetch (duplicate block inserted).
RPC Layer packages/start-client-core/src/client-rpc/serverFnFetcher.ts	Allows an optional per-call fetch override by preferring a provided fetch in call arguments when present.
Core Server-Fn Types & Middleware packages/start-client-core/src/createServerFn.ts, packages/start-client-core/src/createMiddleware.ts	Introduces CustomFetch type; adds fetch?: CustomFetch and internal _callSiteFetch?: CustomFetch across fetcher, middleware options, and execution context; propagates fetch through middleware execution.
Public Exports & Tests packages/start-client-core/src/index.tsx, packages/start-client-core/src/tests/*.test-d.ts	Exports CustomFetch publicly; updates type tests and .test-d.ts assertions to include optional fetch?: CustomFetch.
Docs docs/start/framework/react/guide/middleware.md	Expands middleware docs with header merging, fetch precedence (call-site > later middleware > earlier middleware > global), call-site override examples, chained middleware examples, and SSR notes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Client
  participant RPC as ServerFnFetcher
  participant Middleware as MiddlewareChain
  participant Server as ServerFunction

  Note over Client,RPC: Call-site may pass optional fetch
  Client->>RPC: invoke serverFn(payload, opts{ fetch? })
  RPC->>Middleware: deliver payload including _callSiteFetch/fetch
  alt middleware may set/override fetch
    Middleware->>Middleware: set or override ctx.fetch
  end
  Middleware->>Server: call handler with ctx (resolved fetch prioritized)
  Server->>Server: perform network call using resolved fetch implementation
  Server-->>Client: return response

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix: refactor middleware #5517 — overlaps on server-function/middleware plumbing and route-tree generation touching similar files.
• fix: raw response handling #5276 — modifies serverFnFetcher logic; touches the same RPC fetch path.
• feat(start-core): add method and serverFnMeta property to ServerFnCtx #6394 — touches createServerFn middleware/type surface relevant to CustomFetch propagation.

Suggested reviewers

• chorobin
• birkskyum

Poem

"I hop a header, swift and neat,
A fetch that travels from seat to seat.
Middleware whispers, chains that try,
Call-site shouts — the strongest fly.
My route delights — fetches meet!" 🐰

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: introducing the ability to use custom fetch implementations for server functions. It accurately captures the primary feature addition across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 9dd7dbf

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

---

☁️ Nx Cloud last updated this comment at 2026-01-18 19:28:20 UTC

[pkg-pr-new]

More templates

• 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-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• 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-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
• @tanstack/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-authjs
• 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-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6327

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6327

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6327

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6327

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 9dd7dbf

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/start/framework/react/guide/middleware.md (1)

545-545: Minor wording refinement.

Per static analysis, "merged together" can be simplified to "merged" for conciseness while retaining clarity.

✏️ Proposed wording refinement

- When multiple middlewares set headers, they are **merged together**. Later middlewares can add new headers or override headers set by earlier middlewares:
+ When multiple middlewares set headers, they are **merged**. Later middlewares can add new headers or override headers set by earlier middlewares:

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between aa7aadc and 58d101f.

📒 Files selected for processing (1)

• docs/start/framework/react/guide/middleware.md

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

Use relative links to docs/ folder format (e.g., ./guide/data-loading) for internal documentation references

Files:

• docs/start/framework/react/guide/middleware.md

🪛 LanguageTool

docs/start/framework/react/guide/middleware.md

[style] ~523-~523: Consider using a different adverb to strengthen your wording.
Context: ...ses the client method executes in a completely different client-side context than se...

(COMPLETELY_ENTIRELY)

---

[style] ~545-~545: ‘merged together’ might be wordy. Consider a shorter alternative.
Context: ...ple middlewares set headers, they are merged together. Later middlewares can add new header...

(EN_WORDINESS_PREMIUM_MERGED_TOGETHER)

⏰ 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

🔇 Additional comments (1)

docs/start/framework/react/guide/middleware.md (1)

525-720: Comprehensive and well-structured documentation for custom fetch and header handling.

The new sections introduce client-side request modification clearly, with well-organized subsections on headers, custom fetch, and precedence rules. The examples progress logically from simple to complex (single middleware, call-site override, chained middlewares), and the precedence tables effectively communicate priority order. The SSR caveat (line 718-719) is appropriately highlighted to prevent common misunderstandings.

I see the documentation imports CustomFetch from '@tanstack/react-start' (lines 605, 627). Please verify this type is exported from the public API surface of the package, as indicated in the PR summary.