feat: custom fetch impl via createStart

[schiller-manuel]

Summary by CodeRabbit

• New Features

  • Added global fetch configuration option for server functions via createStart, enabling default custom fetch behavior across all server function calls.

• Documentation

  • Updated Fetch Override Precedence table to clarify fetch priority hierarchy.
  • Added Global Fetch via createStart guide section with configuration examples and SSR behavior notes.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR introduces a global fetch configuration option for server functions in React Start. A new serverFns.fetch property in StartInstanceOptions allows setting a default fetch implementation for all server function calls, positioned in the precedence hierarchy below call-site and middleware overrides but above native fetch. Documentation and end-to-end tests are updated accordingly.

Changes

Cohort / File(s)	Summary
Documentation docs/start/framework/react/guide/middleware.md	Adds precedence entry for createStart-based global fetch override (position 4) and new Default fetch entry (position 5); introduces Global Fetch via createStart section with code examples and SSR notes
Core Type Exports packages/start-client-core/src/index.tsx	Exports new StartInstanceOptions type from createStart module
Core Configuration packages/start-client-core/src/createStart.ts	Adds optional serverFns.fetch property to StartInstanceOptions with JSDoc; imports CustomFetch type for type safety
Client RPC Logic packages/start-client-core/src/client-rpc/createClientRpc.ts	Adds getStartOptions import; modifies fetch resolution to use getStartOptions()?.serverFns?.fetch when available, fallback to native fetch
E2E Start Configuration e2e/react-start/server-functions/src/start.ts	Exports startInstance constant from createStart; introduces globalServerFnFetch helper that injects x-global-fetch: true header and delegates to fetch
E2E Type Augmentation e2e/react-start/server-functions/src/routeTree.gen.ts	Updates import from createStart to startInstance from ./start.ts; extends @tanstack/react-start Register interface with config property typed as Awaited<ReturnType<typeof startInstance.getOptions>>
E2E Test Component e2e/react-start/server-functions/src/routes/custom-fetch.tsx	Adds three new tests (Test 6–Test 8) for global fetch precedence; expands state tracking with globalFetchResult, middlewareOverridesGlobalResult, directOverridesGlobalResult; updates Test 5 description; adjusts precedence hierarchy text
E2E Test Assertions e2e/react-start/server-functions/tests/server-functions.spec.ts	Renames existing test; adds three new test cases validating: global fetch usage (x-global-fetch header), middleware override of global fetch, and direct call-site override of global fetch

Sequence Diagram(s)

sequenceDiagram
    participant Client as Client Code
    participant RPC as createClientRpc
    participant Options as getStartOptions
    participant Fetch as fetch()
    
    rect rgba(100, 200, 150, 0.5)
    Note over Client,Fetch: Fetch Selection Precedence
    end
    
    Client->>RPC: Call server function (optional callSite fetch)
    RPC->>RPC: Check for callSite fetch override
    alt callSite fetch provided
        RPC->>Fetch: Use callSite fetch
    else no callSite fetch
        RPC->>Options: getStartOptions()
        Options-->>RPC: Returns config with serverFns.fetch
        alt middleware fetch interceptor exists
            RPC->>Fetch: Use middleware fetch
        else no middleware
            alt serverFns.fetch configured
                RPC->>Fetch: Use global serverFns.fetch
            else no global fetch
                RPC->>Fetch: Use native fetch
            end
        end
    end
    RPC->>Fetch: Execute with selected fetch
    Fetch-->>RPC: Response
    RPC-->>Client: Return result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: allow custom fetch impl for server functions #6327: Implements the same global server function fetch feature with identical precedence logic and client/server-side wiring.
• fix: add StartInstance re-export which is used as a return type from createStart #5259: Modifies the public type exports in packages/start-client-core/src/index.tsx alongside this PR's StartInstanceOptions export.
• fix: register createServerFn fetcher as serializable #5268: Updates createStart and related types for server function fetch handling and module augmentation patterns.

Suggested labels

documentation, package: start-client-core

Suggested reviewers

• chorobin
• birkskyum

Poem

🐰 A global fetch hops into the frame,
With precedence rules—no two are the same!
Middleware bounds it, call-sites override,
While native fetch waits quietly beside,
The hierarchy's clear, the defaults now shine!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ 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%.	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 'feat: custom fetch impl via createStart' directly and clearly summarizes the main change: introducing custom fetch implementation capability through the createStart configuration option.

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

✨ Finishing touches

• 📝 Generate docstrings

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 markdownlint-cli2 (0.18.1)

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

markdownlint-cli2 v0.18.1 (markdownlint v0.38.0)
Finding: docs/start/framework/react/guide/middleware.md
Linting: 1 file(s)
Summary: 0 error(s)
Error: EACCES: permission denied, open '/markdownlint-cli2-results.json'
at async open (node:internal/fs/promises:640:25)
at async Object.writeFile (node:internal/fs/promises:1214:14)
at async Promise.all (index 0)
at async outputSummary (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:877:5)
at async main (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:1053:25)
at async file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2-bin.mjs:12:22 {
errno: -13,
code: 'EACCES',
syscall: 'open',
path: '/markdownlint-cli2-results.json'
}

---

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

[nx-cloud]

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

---

View your CI Pipeline Execution ↗ for commit 1beaf57

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	9m 6s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	34s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-01-19 00:04:33 UTC

[pkg-pr-new]

More templates

• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• 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-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/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 1beaf57