Add configureClient fetch interceptor for client-side requests

Introduces configureClient({ fetch }) so apps can install a custom fetch
used by every framework-initiated client request: route-state fetches on
navigation, useRevalidate, prefetch, and <Form> submissions. Enables
forwarding an Authorization header (e.g. a bearer token held on the
client) so server-side loaders can read it from request.headers on both
the initial SSR request and every subsequent client-triggered fetch.

Author: claude

.changeset/client-fetch-interceptor.md

@@ -0,0 +1,5 @@
+---
+"@pracht/core": minor
+---
+
+Add `configureClient({ fetch })` so apps can install a custom fetch implementation for every framework-initiated client request — route-state fetches during navigation, revalidation, and prefetch, as well as `<Form>` submissions. Enables forwarding auth headers (e.g. `Authorization: Bearer …`) to loaders on client-side navigations without losing them after initial SSR.

docs/DATA_LOADING.md

@@ -69,6 +69,49 @@ For SPA routes, the initial HTML can still include the matched shell and an
 optional shell `Loading` export so the page is not blank before the route-state
 request resolves.
 
+### Forwarding headers from the client
+
+Pracht's client runtime issues its own fetches for:
+
+- Navigation route-state fetches
+- `useRevalidate()` calls
+- Prefetching (hover / viewport / intent)
+- `<Form>` submissions
+
+By default these fetches only set framework headers (e.g.
+`x-pracht-route-state-request`). If a loader needs to read a header that the
+browser does not attach automatically — most commonly `Authorization: Bearer …`
+from a client-held token — install a custom fetch with `configureClient()`:
+
+```ts
+// src/routes.ts
+import { configureClient, defineApp } from "@pracht/core";
+
+configureClient({
+  fetch: (input, init) =>
+    fetch(input, {
+      ...init,
+      credentials: "include",
+      headers: {
+        ...(init?.headers as Record<string, string> | undefined),
+        Authorization: `Bearer ${getToken()}`,
+      },
+    }),
+});
+
+export const app = defineApp({ /* ... */ });
+```
+
+Because `src/routes.ts` is imported by the generated client entry before
+`initClientRouter` runs, the configuration is in place before the first
+client fetch. On the server, loaders can then read the header from
+`request.headers.get("authorization")` on both the initial SSR request and
+every subsequent client-triggered route-state fetch.
+
+Cookies (used by the session-based auth recipe) continue to flow by default
+for same-origin deployments; set `credentials: "include"` as shown above only
+if you serve loaders from a cross-origin host.
+
 ### Error handling
 
 Throw `PrachtHttpError` for structured error responses:

examples/docs/src/routes/docs/recipes-auth.md

@@ -258,3 +258,44 @@ export const app = defineApp({
 - For OAuth flows, handle the callback in an API route (`src/api/auth/callback.ts`) that sets the session cookie and redirects.
 - For role-based access, extend the middleware to check permissions and return a `403` or redirect.
 - Never store passwords or secrets in loader data — it gets serialized to the client. Only return what the component needs.
+
+---
+
+## Bearer tokens instead of cookies
+
+If your auth uses a short-lived bearer token kept on the client (e.g. returned
+from an OAuth token endpoint) rather than a session cookie, the token must be
+attached to every client-initiated route-state fetch — not just the initial
+SSR request. Use `configureClient()` at the top of `src/routes.ts` so the
+framework's own navigation, revalidation, prefetch, and `<Form>` fetches all
+forward it:
+
+```ts [src/routes.ts]
+import { configureClient, defineApp } from "@pracht/core";
+import { getToken } from "./auth/token";
+
+configureClient({
+  fetch: (input, init) => {
+    const token = getToken();
+    return fetch(input, {
+      ...init,
+      headers: {
+        ...(init?.headers as Record<string, string> | undefined),
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+    });
+  },
+});
+
+export const app = defineApp({ /* ... */ });
+```
+
+Loaders then read the header the same way on either the first SSR render or
+subsequent client navigations:
+
+```ts
+export async function loader({ request }: LoaderArgs) {
+  const token = request.headers.get("authorization")?.replace(/^Bearer /, "");
+  // ...
+}
+```

packages/framework/src/index.ts

@@ -14,6 +14,7 @@ export { useIsHydrated } from "./hydration.ts";
 export { Suspense, lazy } from "preact-suspense";
 export {
   applyDefaultSecurityHeaders,
+  configureClient,
   Form,
   handlePrachtRequest,
   readHydrationState,
@@ -74,9 +75,11 @@ export type {
   PrachtAppConfig,
 } from "./types.ts";
 export type {
+  ConfigureClientOptions,
   FormProps,
   HandlePrachtRequestOptions,
   Location,
+  PrachtClientFetch,
   PrachtRuntimeDiagnosticPhase,
   PrachtRuntimeDiagnostics,
   RouteStateResult,

packages/framework/src/runtime-client-fetch.ts

@@ -6,6 +6,65 @@ export type RouteStateResult =
   | { type: "redirect"; location: string }
   | { type: "error"; error: SerializedRouteError };
 
+/**
+ * A fetch implementation matching the standard Web fetch signature.
+ *
+ * Provided to {@link configureClient} to customize how the framework's
+ * client runtime (navigation, revalidation, prefetch, `<Form>`) performs
+ * HTTP requests — e.g. to forward an `Authorization` header from a
+ * client-held token into loader requests.
+ */
+export type PrachtClientFetch = typeof fetch;
+
+export interface ConfigureClientOptions {
+  /**
+   * Replacement fetch function used for every framework-initiated client
+   * request: route-state fetches during navigation/revalidation/prefetch,
+   * and `<Form>` submissions.
+   *
+   * The function receives the same `(input, init)` arguments as the
+   * standard `fetch`. The framework sets its own required headers
+   * (e.g. `x-pracht-route-state-request`) on `init.headers`; callers
+   * should merge them when adding their own.
+   */
+  fetch?: PrachtClientFetch;
+}
+
+let configuredClientFetch: PrachtClientFetch | undefined;
+
+/**
+ * Configure the client runtime. Call this once at app startup (e.g. at the
+ * top of your `src/routes.ts`) to install a custom fetch implementation
+ * that every framework-initiated client request will flow through.
+ *
+ * Typical use is forwarding an `Authorization` header on client-side
+ * navigations, revalidations, prefetches, and `<Form>` submissions so
+ * server-side loaders can read it from `request.headers`.
+ *
+ * ```ts
+ * configureClient({
+ *   fetch: (input, init) =>
+ *     fetch(input, {
+ *       ...init,
+ *       credentials: "include",
+ *       headers: {
+ *         ...(init?.headers as Record<string, string> | undefined),
+ *         Authorization: `Bearer ${getToken()}`,
+ *       },
+ *     }),
+ * });
+ * ```
+ *
+ * Passing `undefined` for `fetch` resets to the global `fetch`.
+ */
+export function configureClient(options: ConfigureClientOptions = {}): void {
+  configuredClientFetch = options.fetch;
+}
+
+export function getConfiguredClientFetch(): PrachtClientFetch {
+  return configuredClientFetch ?? fetch;
+}
+
 export function buildRouteStateUrl(url: string): string {
   const separator = url.includes("?") ? "&" : "?";
   return `${url}${separator}_data=1`;
@@ -16,7 +75,8 @@ export async function fetchPrachtRouteState(
   options?: { useDataParam?: boolean },
 ): Promise<RouteStateResult> {
   const fetchUrl = options?.useDataParam ? buildRouteStateUrl(url) : url;
-  const response = await fetch(fetchUrl, {
+  const clientFetch = getConfiguredClientFetch();
+  const response = await clientFetch(fetchUrl, {
     headers: options?.useDataParam
       ? {}
       : { [ROUTE_STATE_REQUEST_HEADER]: "1", "Cache-Control": "no-cache" },

packages/framework/src/runtime-hooks.ts

@@ -8,7 +8,11 @@ import {
   SAFE_METHODS,
 } from "./runtime-constants.ts";
 import { deserializeRouteError, type SerializedRouteError } from "./runtime-errors.ts";
-import { fetchPrachtRouteState, navigateToClientLocation } from "./runtime-client-fetch.ts";
+import {
+  fetchPrachtRouteState,
+  getConfiguredClientFetch,
+  navigateToClientLocation,
+} from "./runtime-client-fetch.ts";
 import type { RouteParams } from "./types.ts";
 
 export interface PrachtHydrationState<TData = unknown> {
@@ -198,7 +202,8 @@ export function Form(props: FormProps) {
       }
 
       event.preventDefault();
-      const response = await fetch(props.action ?? form.action, {
+      const clientFetch = getConfiguredClientFetch();
+      const response = await clientFetch(props.action ?? form.action, {
         method: formMethod,
         body: new FormData(form),
         redirect: "manual",

packages/framework/src/runtime.ts

@@ -433,4 +433,10 @@ export {
   type PrachtHydrationState,
   type StartAppOptions,
 } from "./runtime-hooks.ts";
-export { fetchPrachtRouteState, type RouteStateResult } from "./runtime-client-fetch.ts";
+export {
+  configureClient,
+  fetchPrachtRouteState,
+  type ConfigureClientOptions,
+  type PrachtClientFetch,
+  type RouteStateResult,
+} from "./runtime-client-fetch.ts";

packages/framework/test/configure-client.test.ts

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+import { h, render } from "preact";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { configureClient, Form } from "../src/index.ts";
+import { fetchPrachtRouteState } from "../src/runtime.ts";
+
+function createJsonResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    headers: {
+      "content-type": "application/json",
+    },
+    ...init,
+  });
+}
+
+describe("configureClient", () => {
+  afterEach(() => {
+    // Reset to default (global fetch) between tests.
+    configureClient({ fetch: undefined });
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("routes fetchPrachtRouteState through the configured fetch", async () => {
+    const customFetch = vi.fn(async () => createJsonResponse({ data: { hello: "world" } }));
+
+    configureClient({ fetch: customFetch as unknown as typeof fetch });
+
+    const result = await fetchPrachtRouteState("/foo");
+
+    expect(customFetch).toHaveBeenCalledTimes(1);
+    expect(customFetch).toHaveBeenCalledWith(
+      "/foo",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          "Cache-Control": "no-cache",
+          "x-pracht-route-state-request": "1",
+        }),
+        redirect: "manual",
+      }),
+    );
+    expect(result).toEqual({ type: "data", data: { hello: "world" } });
+  });
+
+  it("falls back to the global fetch when no configuration is set", async () => {
+    const globalFetch = vi.fn(async () => createJsonResponse({ data: 1 }));
+    vi.stubGlobal("fetch", globalFetch);
+
+    await fetchPrachtRouteState("/bar");
+
+    expect(globalFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("resets to the global fetch when fetch: undefined is passed", async () => {
+    const customFetch = vi.fn(async () => createJsonResponse({ data: 1 }));
+    const globalFetch = vi.fn(async () => createJsonResponse({ data: 2 }));
+    vi.stubGlobal("fetch", globalFetch);
+
+    configureClient({ fetch: customFetch as unknown as typeof fetch });
+    await fetchPrachtRouteState("/a");
+    expect(customFetch).toHaveBeenCalledTimes(1);
+    expect(globalFetch).not.toHaveBeenCalled();
+
+    configureClient({ fetch: undefined });
+    await fetchPrachtRouteState("/b");
+    expect(customFetch).toHaveBeenCalledTimes(1);
+    expect(globalFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards an Authorization header injected by the configured fetch to client navigation fetches", async () => {
+    const seenHeaders: Array<Record<string, string>> = [];
+    const customFetch = vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+      seenHeaders.push((init?.headers as Record<string, string>) ?? {});
+      return createJsonResponse({ data: null });
+    });
+
+    configureClient({
+      fetch: (input, init) => {
+        const headers = {
+          ...(init?.headers as Record<string, string> | undefined),
+          Authorization: "Bearer token-123",
+        };
+        return customFetch(input, { ...init, headers });
+      },
+    });
+
+    await fetchPrachtRouteState("/baz");
+
+    expect(seenHeaders[0]).toMatchObject({
+      Authorization: "Bearer token-123",
+      "x-pracht-route-state-request": "1",
+      "Cache-Control": "no-cache",
+    });
+  });
+
+  it("routes <Form> submissions through the configured fetch", async () => {
+    const customFetch = vi.fn<typeof fetch>(async () => new Response(null, { status: 204 }));
+    configureClient({ fetch: customFetch });
+
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+
+    try {
+      render(
+        h(
+          Form,
+          { action: "/api/do", method: "post" },
+          h("input", { name: "x", defaultValue: "y" }),
+          h("button", { type: "submit" }, "Go"),
+        ),
+        root,
+      );
+
+      const form = root.querySelector("form")!;
+      form.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+      // let the microtask queue settle
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(customFetch).toHaveBeenCalledTimes(1);
+      const [url, init] = customFetch.mock.calls[0]!;
+      expect(url).toBe("/api/do");
+      expect(init?.method).toBe("POST");
+      expect(init?.redirect).toBe("manual");
+    } finally {
+      render(null, root);
+      root.remove();
+    }
+  });
+});