[Proposal] Support a custom fetch function on HydratedRouter for manifest and data requests

[jasonhuang-dev]

Summary

We propose adding a fetch prop to HydratedRouter (and potentially RouterProvider) that allows applications to supply a custom function to handle all internal fetch requests made by React Router — including the __manifest endpoint and .data requests.

This was briefly proposed by @rossipedia in #14800, and we'd like to expand on that idea with an additional motivating use case and a more detailed API proposal.

---

Motivation

Use case 1: Detecting client/server version mismatch (from #14800)

As discussed in #14800, applications running rolling deployments need to detect when the server has been updated to a new version and react accordingly (e.g. trigger a document reload, show a "new version available" banner). A custom fetch function makes it straightforward to inspect response headers and act on version information.

Use case 2: CDN / gateway region routing for manifest requests

In applications deployed across multiple regions with rolling deployments, a __manifest request from a client that was served by Region A may be routed by the CDN to Region B — which may not yet have the new version deployed. Many CDN and API gateway setups support pinning a request to a specific origin or region via a custom request header (routing hint headers are a common pattern in multi-region infrastructure).

Currently, there is no supported way to inject such headers into React Router's internal fetch(url, { signal }) call for the manifest endpoint. The only workaround is monkey-patching window.fetch, which is undesirable because it:

• Affects all fetch calls on the page, not just React Router's internal ones
• Is brittle and hard to maintain
• Goes against the principle of least surprise

This also makes it possible to replace React Router's default window.fetch entirely with a third-party HTTP client such as axios, enabling features like automatic retries, request interceptors, and richer error handling out of the box.

---

Proposed API

Add an optional fetch prop to HydratedRouter:

// entry.client.tsx
import axios from 'axios';

<HydratedRouter
  fetch={async (input, init) => {
    const response = await axios({
      url: input.toString(),
      method: init?.method ?? 'GET',
      headers: {
        ...init?.headers,
        'x-region': getRegion(),
      },
      signal: init?.signal,
      data: init?.body,
    });

    // Wrap axios response back into a standard Response
    return new Response(JSON.stringify(response.data), {
      status: response.status,
      headers: response.headers as HeadersInit,
    });
  }}
/>

The prop would default to window.fetch if not provided, making it fully backward compatible.

Type signature:

type RouterFetch = (
  input: RequestInfo | URL,
  init?: RequestInit,
) => Promise<Response>;

Why HydratedRouter (not react-router.config.ts)?

react-router.config.ts is a build-time configuration. Custom fetch logic typically requires runtime values — e.g. a region identifier embedded in the HTML by the server, auth tokens stored in memory, or environment-specific configuration. HydratedRouter lives in entry.client.tsx and is the natural place for client-side runtime customization.

---

Additional use cases this unlocks

Beyond the two motivating examples above, a custom fetch function enables the community to implement patterns that are currently impossible or require monkey-patching:

• Injecting authentication headers (e.g. Authorization: Bearer ...) on .data requests
• Using a custom HTTP client (e.g. one that handles retries or circuit-breaking)
• Adding request tracing headers for observability
• Implementing custom caching strategies on top of manifest responses

---

Related

• [Framework] Add a way to reload the frontend when the backend changes #14800 — Add a way to reload the frontend when the backend changes (custom fetch on HydratedRouter suggested by @rossipedia in comments)

[rossipedia]

I have this implemented in #15465, but I need to fix some conflicts and update it to apply to manifest fetches as well, that's a good catch.

[brophdawg11]

Closing as a dup of #15461, which is being implemented in #15586.

also see #15590 for a more focused proposal on handling manifest mismatches