@raf-query/react 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -1,8 +1,18 @@
 # Changelog
 
+## [0.3.0](https://github.com/KATT/raf-query/compare/0.2.8...0.3.0) (2026-10-13)
+
+### ⚠ BREAKING CHANGES
+
+* RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61))
+
+### Features
+
+* RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61)) ([772de79](https://github.com/KATT/raf-query/commit/772de796adfdf267a9184fd75624ff30ae53f4fc)), references [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59)
+
 ## [0.2.8](https://github.com/KATT/raf-query/compare/0.2.7...0.2.8) (2026-10-13)
 
-* **codesandbox:** speed up the branch sync ([#60](https://github.com/KATT/raf-query/issues/60)) ([9099cb2](https://github.com/KATT/raf-query/commit/9099cb2ce937104d5feb8c7033233e701f412a28))
+- **codesandbox:** speed up the branch sync ([#60](https://github.com/KATT/raf-query/issues/60)) ([9099cb2](https://github.com/KATT/raf-query/commit/9099cb2ce937104d5feb8c7033233e701f412a28))
 
 ## [0.2.7](https://github.com/KATT/raf-query/compare/0.2.6...0.2.7) (2026-10-13)
 

package/README.md

@@ -32,12 +32,11 @@ The same issue tracker, built on two frameworks so the integrations can be compa
 
 `@raf-query/react` subpath entries for framework integrations and tooling:
 
-| Entry                              | Use                                                                    |
-| ---------------------------------- | ---------------------------------------------------------------------- |
-| `@raf-query/react/tanstack-router` | Streams the router's query cache to the client during SSR              |
-| `@raf-query/react/rsc`             | `HydrationBoundary` for passing server-component queries to the client |
-| `@raf-query/react/next`            | `QueryProvider` for Next.js App Router                                 |
-| `@raf-query/react/devtools`        | [Devtools](#devtools) panel for inspecting the cache in development    |
+| Entry                              | Use                                                                 |
+| ---------------------------------- | ------------------------------------------------------------------- |
+| `@raf-query/react/tanstack-router` | Streams the router's query cache to the client during SSR           |
+| `@raf-query/react/rsc`             | `QueryProvider` and `HydrationBoundary` for React Server Components |
+| `@raf-query/react/devtools`        | [Devtools](#devtools) panel for inspecting the cache in development |
 
 ## Principles
 
@@ -435,7 +434,7 @@ Like `prefetch` in a loader, `useWaterfall` refetches stale cached data in the b
 
 The name is the warning: each waterfall is an extra round trip after render. First try to get the input from route params so the loader can start it, or have the backend return it with its parent.
 
-During SSR the `queryFn` runs on the server. TanStack Start server functions work there. Next.js rejects server actions called while rendering, so in Next.js start the dependent query in the server component instead:
+In TanStack Start the `queryFn` runs on the server during SSR, and the router streams the result. Under the `/rsc` `QueryProvider` it starts nothing on the server: the reader's Suspense boundary renders its fallback there, and the query loads in the browser. To have it in the HTML, start the dependent query in the server component instead:
 
 ```tsx
 const post = await qc.fetch(postQuery, { slug });
@@ -518,7 +517,7 @@ export function getRouter() {
 
 `setupRouterIntegration` streams queries during SSR, clears the request's cache when the response finishes, and turns `redirect()` thrown from a `queryFn` into a router navigation. `getRouter` runs per request on the server, so each request gets its own client. Options: `dehydrateOptions` (`filter`, `keepErrors`, `serializeData`), `hydrateOptions` (`deserializeData`), and `handleRedirects: false` to handle redirects yourself. By default a server error crosses to the browser as a `RedactedError` naming the query, so its message doesn't leak into the page.
 
-### Next.js App Router
+### React Server Components (Next.js App Router)
 
 ```tsx
 // app/get-query-client.ts
@@ -530,7 +529,7 @@ export const getQueryClient = cache(() => new QueryClient());
 
 ```tsx
 // app/layout.tsx
-import { QueryProvider } from "@raf-query/react/next";
+import { QueryProvider } from "@raf-query/react/rsc";
 
 export default function RootLayout(props: { children: React.ReactNode }) {
 	return (
@@ -570,8 +569,9 @@ export default async function Page(props: {
 ```
 
 - `getQueryClient` is scoped to one request by React's `cache()`.
-- `HydrationBoundary` sends the request client's entries to the browser cache; pending ones stream as promises. Render one in each server component that starts queries for client components. Entries already sent in this request are skipped. The browser takes the server's data when it's newer than its own. Otherwise it keeps its copy and refetches it if stale. That covers a payload the router replays from its cache (back and forward) and a `prefetch` still pending on the server.
-- `QueryProvider` creates the browser client, and streams queries that client components start during SSR (`useWaterfall`) into the HTML. Pass `config` for the client's options; it must be serializable.
+- `HydrationBoundary` sends the request client's entries to the browser cache; pending ones stream as promises through the RSC payload. Render one in each server component that starts queries for client components. Entries already sent in this request are skipped.
+- The browser takes whichever copy is newer, by when it was fetched (`updatedAt`, so server and browser clocks should agree). When it has no data and no request of its own, it resumes the server's pending request. When it has data, or its own request in flight, it waits for the server's instead of fetching again, and takes it if newer. If it keeps its own copy (the server's is older, as in a payload the router replays from its cache on back and forward, or the server's request failed), it refetches it if stale.
+- `QueryProvider` creates one client per server render and one per browser tab. The server render starts no request: a client component reading a query no `HydrationBoundary` sent renders its Suspense fallback on the server, and the query loads in the browser. That boundary renders in the browser through React's error recovery, with the digest Next.js uses for `ssr: false`, so Next.js doesn't report it; other frameworks pass it to `onRecoverableError`. Pass `config` for the client's options; it must be serializable.
 - Server components that only render data can `await qc.fetch(...)` anywhere; the per-request client makes one request per query, whatever its `staleTime`.
 - `fetch` returns data, not a handle. When a server component renders the data and also hands the query to a client component, pass `await qc.ensure(...)`: after the `fetch` it resolves from the cache, and the client component gets the data from `useQuery` without a promise.
 - Factories can call server actions: server components call them directly, and the browser calls them on refetch. Validate their arguments, since anyone can call them. The browser runs a page's server actions one at a time, so refetches wait for each other and for any pending mutation. For parallel requests, have the `queryFn` call a [Route Handler](https://nextjs.org/docs/app/api-reference/file-conventions/route), as [`examples/nextjs`](examples/nextjs) does.

package/dist/browser-requests.mjs

@@ -0,0 +1,38 @@
+import { Query } from "@raf-query/core";
+//#region src/browser-requests.ts
+/**
+* The digest Next.js gives a boundary that renders only in the browser
+* (`next/dynamic` with `ssr: false`); it doesn't report those errors.
+*/
+const clientRendering = "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+const browserOnly = /* @__PURE__ */ new WeakSet();
+/**
+* Make a server client's render start no request: it reads what a
+* `HydrationBoundary` sent, and anything else loads in the browser.
+*/
+function requestInBrowserOnly(client) {
+	browserOnly.add(client);
+}
+/** Whether a render may start `client`'s requests (`useWaterfall`). */
+function startsRequests(client) {
+	return !(client.isServer && browserOnly.has(client));
+}
+/**
+* Thrown by a server render's read of a query no `HydrationBoundary` sent.
+* React renders the nearest Suspense fallback, and the browser renders the
+* content.
+*/
+var BrowserRenderError = class extends Error {
+	digest = clientRendering;
+	constructor(hash) {
+		super(`Query ${hash} loads in the browser: no HydrationBoundary sent it`);
+	}
+};
+/** Throw {@link BrowserRenderError} if reading `query` would start a request here. */
+function assertSent(client, query) {
+	if (startsRequests(client)) return;
+	const state = Query.getUnsafe(query);
+	if (!state.hasData && !state.isFetching && state.status !== "error") throw new BrowserRenderError(query.hash);
+}
+//#endregion
+export { BrowserRenderError, assertSent, requestInBrowserOnly, startsRequests };

package/dist/hydrate.mjs

@@ -1,15 +1,9 @@
 "use client";
 import { hydrate } from "./client.mjs";
 import { useQueryClient } from "./provider.mjs";
-import { sentHashes } from "./sent.mjs";
 import { Query, hashKey } from "@raf-query/core";
 import { useEffect, useState } from "react";
 //#region src/hydrate.tsx
-/** In the SSR pass, entries from the RSC payload needn't be streamed again. */
-function markSent(client, state) {
-	const sent = sentHashes(client);
-	for (const query of state.queries) sent.add(hashKey(query.key));
-}
 /**
 * Entries the client has no data for, which children need during this
 * render, and entries it already shows, which must wait for a commit.
@@ -37,7 +31,6 @@ function Hydrate(props) {
 	const [hydrated, setHydrated] = useState();
 	if (hydrated?.state !== state) {
 		const parts = split(client, state);
-		markSent(client, state);
 		hydrate(client, parts.now, options);
 		setHydrated({
 			deferred: parts.deferred,

package/dist/query-provider.d.mts

@@ -0,0 +1,21 @@
+import { QueryClientConfig } from "./client.mjs";
+import { ReactNode } from "react";
+//#region src/query-provider.d.ts
+/**
+ * The query client provider for React Server Components apps. Creates one
+ * client per server render and one per browser tab. The server render
+ * starts no request: client components read what `HydrationBoundary` sent,
+ * and a query nothing sent renders its Suspense fallback there and loads in
+ * the browser.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * <QueryProvider>{props.children}</QueryProvider>
+ * ```
+ */
+export declare function QueryProvider(props: {
+  readonly children?: ReactNode;
+  /** Options for the client it creates. */
+  readonly config?: QueryClientConfig;
+}): import("react").JSX.Element;
+//#endregion

package/dist/query-provider.mjs

@@ -0,0 +1,33 @@
+"use client";
+import { QueryClient } from "./client.mjs";
+import { QueryClientProvider } from "./provider.mjs";
+import { requestInBrowserOnly } from "./browser-requests.mjs";
+import { useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/query-provider.tsx
+/**
+* The query client provider for React Server Components apps. Creates one
+* client per server render and one per browser tab. The server render
+* starts no request: client components read what `HydrationBoundary` sent,
+* and a query nothing sent renders its Suspense fallback there and loads in
+* the browser.
+*
+* ```tsx
+* // app/layout.tsx
+* <QueryProvider>{props.children}</QueryProvider>
+* ```
+*/
+function QueryProvider(props) {
+	const config = props.config;
+	const [client] = useState(() => {
+		const created = new QueryClient(config);
+		requestInBrowserOnly(created);
+		return created;
+	});
+	return /* @__PURE__ */ jsx(QueryClientProvider, {
+		client,
+		children: props.children
+	});
+}
+//#endregion
+export { QueryProvider };

package/dist/rsc.d.mts

@@ -1,4 +1,5 @@
 import { QueryClient } from "./client.mjs";
+import { QueryProvider } from "./query-provider.mjs";
 import { DehydrateOptions } from "@raf-query/core";
 import { ReactNode } from "react";
 //#region src/rsc.d.ts
@@ -23,4 +24,5 @@ export declare function HydrationBoundary(props: {
   readonly client: QueryClient;
   readonly options?: DehydrateOptions;
 }): import("react").JSX.Element;
-//#endregion
+//#endregion
+export { QueryProvider };

package/dist/rsc.mjs

@@ -1,6 +1,7 @@
 import { dehydrate } from "./client.mjs";
-import { sentHashes } from "./sent.mjs";
 import { Hydrate } from "./hydrate.mjs";
+import { sentHashes } from "./sent.mjs";
+import { QueryProvider } from "./query-provider.mjs";
 import { jsx } from "react/jsx-runtime";
 //#region src/rsc.tsx
 /**
@@ -30,4 +31,4 @@ function HydrationBoundary(props) {
 	});
 }
 //#endregion
-export { HydrationBoundary };
+export { HydrationBoundary, QueryProvider };

package/dist/sent.mjs

@@ -1,10 +1,8 @@
 //#region src/sent.ts
 const sentByClient = /* @__PURE__ */ new WeakMap();
 /**
-* Hashes of a client's entries that already have a way to the browser
-* cache: sent by an earlier `HydrationBoundary` of the request, or, in the
-* SSR pass, hydrated from the RSC payload or streamed by `QueryProvider`.
-* Integrations pass it as `sent`, so each entry crosses once.
+* Hashes of the request client's entries an earlier `HydrationBoundary`
+* already sent. Boundaries pass it as `sent`, so each entry crosses once.
 */
 function sentHashes(client) {
 	let sent = sentByClient.get(client);

package/dist/use-query.mjs

@@ -1,6 +1,7 @@
 "use client";
 import { unsafeCast } from "./cast.mjs";
 import { useQueryClient } from "./provider.mjs";
+import { assertSent } from "./browser-requests.mjs";
 import { Query, QueryObserver } from "@raf-query/core";
 import { Effect } from "effect";
 import { use, useEffect, useState, useSyncExternalStore } from "react";
@@ -35,7 +36,9 @@ function storeFor(query, options) {
 	};
 }
 function useQuery(factory, handle, options = {}) {
-	const query = queryFor(useQueryClient(), factory, handle.input);
+	const client = useQueryClient();
+	const query = queryFor(client, factory, handle.input);
+	assertSent(client, query);
 	Query.readUnsafe(query);
 	const refetchInterval = options.refetchInterval;
 	const refetchOnReconnect = options.refetchOnReconnect;

package/dist/use-waterfall.d.mts

@@ -5,7 +5,9 @@ import { InputArgs, QueryFactory, QueryHandle } from "@raf-query/core";
  * at render time (an id from a parent query's data). Each call is a request
  * waterfall: prefer starting the query in a loader or server component.
  * Like `prefetch` in a loader, it refetches stale cached data in the
- * background, once per mount and input.
+ * background, once per mount and input. Under the `/rsc` `QueryProvider` it
+ * starts nothing on the server: the reader's Suspense boundary renders its
+ * fallback there, and the query loads in the browser.
  *
  * ```tsx
  * const author = useWaterfall(authorQuery, { id: post.authorId });

package/dist/use-waterfall.mjs

@@ -1,5 +1,6 @@
 "use client";
 import { useQueryClient } from "./provider.mjs";
+import { startsRequests } from "./browser-requests.mjs";
 import { Query } from "@raf-query/core";
 import { useState } from "react";
 //#region src/use-waterfall.ts
@@ -14,7 +15,9 @@ const waitedFor = /* @__PURE__ */ new WeakSet();
 * at render time (an id from a parent query's data). Each call is a request
 * waterfall: prefer starting the query in a loader or server component.
 * Like `prefetch` in a loader, it refetches stale cached data in the
-* background, once per mount and input.
+* background, once per mount and input. Under the `/rsc` `QueryProvider` it
+* starts nothing on the server: the reader's Suspense boundary renders its
+* fallback there, and the query loads in the browser.
 *
 * ```tsx
 * const author = useWaterfall(authorQuery, { id: post.authorId });
@@ -22,9 +25,11 @@ const waitedFor = /* @__PURE__ */ new WeakSet();
 * ```
 */
 function useWaterfall(factory, ...args) {
-	const query = useQueryClient().getQuery(factory, ...args);
-	const promise = Query.readUnsafe(query);
+	const client = useQueryClient();
+	const query = client.getQuery(factory, ...args);
 	const [started, setStarted] = useState();
+	if (!startsRequests(client)) return query.handle;
+	const promise = Query.readUnsafe(query);
 	if (started !== query.hash) {
 		if (!Query.getUnsafe(query).hasData) waitedFor.add(promise);
 		else if (!waitedFor.delete(promise)) Query.revalidateUnsafe(query);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -35,7 +35,6 @@
     ".": "./dist/index.mjs",
     "./devtools": "./dist/devtools.mjs",
     "./devtools/production": "./dist/devtools-production.mjs",
-    "./next": "./dist/next.mjs",
     "./rsc": "./dist/rsc.mjs",
     "./tanstack-router": {
       "workerd": "./dist/tanstack-router.mjs",
@@ -48,20 +47,16 @@
     }
   },
   "dependencies": {
-    "@raf-query/core": "0.2.8"
+    "@raf-query/core": "0.3.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",
     "effect": "^4.0.0",
-    "next": "^16.0.0",
     "react": "^19.2.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-router": {
       "optional": true
-    },
-    "next": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -74,7 +69,6 @@
     "@vitest/coverage-v8": "5.0.1",
     "effect": "^4.0.1",
     "happy-dom": "21.0.1",
-    "next": "16.4.0",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "typescript": "7.0.2",

package/dist/next.d.mts

@@ -1,25 +0,0 @@
-import { QueryClientConfig } from "./client.mjs";
-import { DehydratedState } from "@raf-query/core";
-import { ReactNode } from "react";
-//#region src/next.d.ts
-declare global {
-  /** Entries streamed by `QueryProvider` during SSR, until the browser client takes over. */
-  var RAF_QUERY_SSR: {
-    push(state: DehydratedState): void;
-  } | undefined;
-}
-/**
- * The query client provider for Next.js App Router. Creates one client per
- * request during SSR and one per tab in the browser.
- *
- * ```tsx
- * // app/layout.tsx
- * <QueryProvider>{props.children}</QueryProvider>
- * ```
- */
-export declare function QueryProvider(props: {
-  readonly children?: ReactNode;
-  /** Options for the client it creates. */
-  readonly config?: QueryClientConfig;
-}): import("react").JSX.Element;
-//#endregion

package/dist/next.mjs

@@ -1,62 +0,0 @@
-"use client";
-import { QueryClient, dehydrate, hydrate } from "./client.mjs";
-import { QueryClientProvider } from "./provider.mjs";
-import { sentHashes } from "./sent.mjs";
-import { Query } from "@raf-query/core";
-import { useState } from "react";
-import { jsx } from "react/jsx-runtime";
-import { useServerInsertedHTML } from "next/navigation";
-//#region src/next.tsx
-function escapeJson(json) {
-	return json.replaceAll("<", String.raw`\u003c`).replaceAll("\u2028", String.raw`\u2028`).replaceAll("\u2029", String.raw`\u2029`);
-}
-/** Hydrate what SSR streamed so far, then hydrate every later chunk on arrival. */
-function receiveStream(client) {
-	const queued = globalThis.RAF_QUERY_SSR;
-	if (Array.isArray(queued)) for (const state of queued) hydrate(client, state);
-	globalThis.RAF_QUERY_SSR = { push: (state) => hydrate(client, state) };
-}
-function hasData(query) {
-	return Query.getUnsafe(query).hasData;
-}
-/**
-* Streams entries that client components loaded during SSR (`useWaterfall`)
-* into the HTML, ahead of the markup that reads them. Entries that arrived
-* through `HydrationBoundary` are skipped: the RSC payload carries them.
-* Data must be JSON-serializable, so only settled entries are sent.
-*/
-function useServerStream(client) {
-	useServerInsertedHTML(() => {
-		const state = dehydrate(client, {
-			filter: hasData,
-			sent: sentHashes(client)
-		});
-		if (state.queries.length === 0) return null;
-		const json = escapeJson(JSON.stringify(state));
-		return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: `(self.RAF_QUERY_SSR=self.RAF_QUERY_SSR||[]).push(${json})` } });
-	});
-}
-/**
-* The query client provider for Next.js App Router. Creates one client per
-* request during SSR and one per tab in the browser.
-*
-* ```tsx
-* // app/layout.tsx
-* <QueryProvider>{props.children}</QueryProvider>
-* ```
-*/
-function QueryProvider(props) {
-	const config = props.config;
-	const [client] = useState(() => {
-		const created = new QueryClient(config);
-		if (!created.isServer) receiveStream(created);
-		return created;
-	});
-	useServerStream(client);
-	return /* @__PURE__ */ jsx(QueryClientProvider, {
-		client,
-		children: props.children
-	});
-}
-//#endregion
-export { QueryProvider };