raf-effect-atom 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,14 +1,20 @@
 # Changelog
 
+## [0.2.1](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.0...raf-effect-atom%400.2.1) (2026-10-23)
+
+### Features
+
+* **raf-effect-atom:** run React Router loaders in the browser after the first page ([bee00a9](https://github.com/KATT/raf-effect-atom/commit/bee00a981fd24fcdc9d746053dcd73dbc7ebc853)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41) [#41](https://github.com/KATT/raf-effect-atom/issues/41)
+
 ## [0.2.0](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.1.0...raf-effect-atom%400.2.0) (2026-10-23)
 
 ### ⚠ BREAKING CHANGES
 
-* **raf-effect-atom:** `dehydrate()` from `raf-effect-atom/next` returns a
+- **raf-effect-atom:** `dehydrate()` from `raf-effect-atom/next` returns a
 
 ### Features
 
-* **raf-effect-atom:** seed each request registry, async seeds included ([62b6180](https://github.com/KATT/raf-effect-atom/commit/62b618098df87e711ddb4c1d633e191ba3353438))
+- **raf-effect-atom:** seed each request registry, async seeds included ([62b6180](https://github.com/KATT/raf-effect-atom/commit/62b618098df87e711ddb4c1d633e191ba3353438))
 
 ## 0.1.0 (2026-10-23)
 

package/README.md

@@ -53,7 +53,7 @@ Each framework has a subpath that gives every server request its own registry an
 
 - `raf-effect-atom/tanstack-router`, for TanStack Router and TanStack Start: `setupRouterAtoms({ router, registry })` in `getRouter`, with `Loader.make(registry)` on the router context.
 - `raf-effect-atom/next`, for the App Router: `prefetch`, `ensure` and `fetch` in server components, which pass the handles to client components as props, and `<HydrateAtoms state={await dehydrate()}>` around them. `makeRequestAtoms({ seed })` makes the same functions over a registry seeded from the request, such as with its cookie.
-- `raf-effect-atom/react-router`, for Framework Mode: `atomsMiddleware(atomsContext)` as the root middleware, loaders that return `atoms.dehydrate()` with their handles, and `HydrationBoundary` in the route component.
+- `raf-effect-atom/react-router`, for Framework Mode: `atomsMiddleware(atomsContext)` as the root middleware and `clientAtomsMiddleware(atomsContext)` as its client middleware, loaders that return `atoms.dehydrate()` with their handles and double as client loaders, and `HydrationBoundary` in the route component.
 
 In development, `useAtomResult` reports a read that starts an atom nothing started, a request waterfall. `<WaterfallDetection mode="throw">` at the root makes it throw to the nearest error boundary. `useWaterfall(source, ...args)` starts an atom whose input exists only in render, marks it as a known waterfall, and returns its handle.
 

package/dist/ReactRouter.d.mts

@@ -3,7 +3,9 @@ import { RegistryProvider } from "./RegistryProvider.mjs";
 import * as EffectHydration from "effect/reactivity/Hydration";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 /**
- * One request's registry, with the loader verbs over it.
+ * One request's registry, with the loader verbs over it. In a client loader,
+ * the browser's registry, whose `dehydrate` returns nothing: its atoms are
+ * already where the components read them.
  *
  * @stability unstable
  * @category models
@@ -71,8 +73,7 @@ export interface AtomsMiddlewareOptions {
  * **Gotchas**
  *
  * It's server middleware: export it as the root route's `middleware`, not
- * `clientMiddleware`. In the browser, the root's `RegistryProvider` holds
- * the registry.
+ * `clientMiddleware`, which takes `clientAtomsMiddleware`.
  *
  * **Example**
  *
@@ -91,4 +92,46 @@ export interface AtomsMiddlewareOptions {
  * @since 0.1.0
  */
 export declare const atomsMiddleware: (context: AtomsContext, options?: AtomsMiddlewareOptions) => <Result>(args: MiddlewareArgs, next: () => Promise<Result>) => Promise<Result>;
+/**
+ * Creates a root client middleware that gives client loaders the browser's
+ * registry, under the context `atomsMiddleware` uses on the server.
+ *
+ * **When to use**
+ *
+ * Export it as the root route's `clientMiddleware`, and each route's loader
+ * function as both its `loader` and its `clientLoader`. The first page's loaders run on
+ * the server and stream their atoms in; after that, navigations run the
+ * loaders in the browser. `ensure` then renders what the browser's registry
+ * holds without a request, and a link's prefetch doesn't fetch a route's
+ * `.data` that the click would fetch again.
+ *
+ * **Details**
+ *
+ * The registry is the one the mounted `RegistryProvider` provides. Its
+ * `dehydrate` returns nothing, so a loader's data has the same shape in
+ * the browser and on the server, and `HydrationBoundary` has nothing to do.
+ *
+ * **Gotchas**
+ *
+ * The atoms run in the browser, so their RPC protocol must reach the server
+ * from there, as it does for anything a component starts.
+ *
+ * **Example**
+ *
+ * ```ts
+ * // app/root.tsx
+ * export const middleware = [atomsMiddleware(atomsContext)]
+ * export const clientMiddleware = [clientAtomsMiddleware(atomsContext)]
+ *
+ * // app/routes/issue.tsx: one function for both, since React Router
+ * // removes `loader` from the browser's bundle.
+ * export const loader = load
+ * export const clientLoader = load
+ * ```
+ *
+ * @stability unstable
+ * @category integrations
+ * @since 0.2.0
+ */
+export declare const clientAtomsMiddleware: (context: AtomsContext) => <Result>(args: MiddlewareArgs, next: () => Promise<Result>) => Promise<Result>;
 export { RegistryProvider };

package/dist/ReactRouter.mjs

@@ -1,6 +1,7 @@
 import { dehydrate } from "./Hydration.mjs";
 import { make, settled } from "./RequestRegistry.mjs";
 import { make as make$1 } from "./Loader.mjs";
+import { current } from "./internal/registry.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
 import * as Predicate from "effect/Predicate";
 // src/ReactRouter.ts
@@ -10,8 +11,11 @@ import * as Predicate from "effect/Predicate";
 * A root `middleware` gives each server request its own registry, under a
 * router context the app creates. Loaders start atoms with its verbs and
 * return its `dehydrate()` with their data; the route component hydrates it
-* with `HydrationBoundary`, inside the root's `RegistryProvider`. Nothing is
-* imported from `react-router`.
+* with `HydrationBoundary`, inside the root's `RegistryProvider`. A root
+* `clientMiddleware` puts the browser's registry under the same context, so
+* one function can be both the route's `loader` and its `clientLoader`: after the first
+* page, loaders run in the browser, where `ensure` finds what the registry
+* already holds. Nothing is imported from `react-router`.
 *
 * **Example**
 *
@@ -26,14 +30,18 @@ import * as Predicate from "effect/Predicate";
 * import { atomsMiddleware } from "raf-effect-atom/react-router"
 *
 * export const middleware = [atomsMiddleware(atomsContext)]
+* export const clientMiddleware = [clientAtomsMiddleware(atomsContext)]
 *
 * // app/routes/issue.tsx
-* export async function loader(args: Route.LoaderArgs) {
+* async function load(args: Route.LoaderArgs) {
 *   const atoms = args.context.get(atomsContext)
 *   const handle = await atoms.ensure(issue, Number(args.params.id))
 *   return { atoms: atoms.dehydrate(), issue: handle }
 * }
 *
+* export const loader = load
+* export const clientLoader = load
+*
 * export default function IssueRoute(props: Route.ComponentProps) {
 *   return (
 *     <HydrationBoundary state={props.loaderData.atoms}>
@@ -64,8 +72,7 @@ import * as Predicate from "effect/Predicate";
 * **Gotchas**
 *
 * It's server middleware: export it as the root route's `middleware`, not
-* `clientMiddleware`. In the browser, the root's `RegistryProvider` holds
-* the registry.
+* `clientMiddleware`, which takes `clientAtomsMiddleware`.
 *
 * **Example**
 *
@@ -135,4 +142,64 @@ const disposeAfter = (body, registry) => {
 		}
 	});
 };
-export { RegistryProvider, atomsMiddleware };
+const browserAtoms = /* @__PURE__ */ new WeakMap();
+const browserAtomsOf = (registry) => {
+	let atoms = browserAtoms.get(registry);
+	if (atoms === void 0) {
+		atoms = {
+			...make$1(registry),
+			dehydrate: () => [],
+			registry
+		};
+		browserAtoms.set(registry, atoms);
+	}
+	return atoms;
+};
+/**
+* Creates a root client middleware that gives client loaders the browser's
+* registry, under the context `atomsMiddleware` uses on the server.
+*
+* **When to use**
+*
+* Export it as the root route's `clientMiddleware`, and each route's loader
+* function as both its `loader` and its `clientLoader`. The first page's loaders run on
+* the server and stream their atoms in; after that, navigations run the
+* loaders in the browser. `ensure` then renders what the browser's registry
+* holds without a request, and a link's prefetch doesn't fetch a route's
+* `.data` that the click would fetch again.
+*
+* **Details**
+*
+* The registry is the one the mounted `RegistryProvider` provides. Its
+* `dehydrate` returns nothing, so a loader's data has the same shape in
+* the browser and on the server, and `HydrationBoundary` has nothing to do.
+*
+* **Gotchas**
+*
+* The atoms run in the browser, so their RPC protocol must reach the server
+* from there, as it does for anything a component starts.
+*
+* **Example**
+*
+* ```ts
+* // app/root.tsx
+* export const middleware = [atomsMiddleware(atomsContext)]
+* export const clientMiddleware = [clientAtomsMiddleware(atomsContext)]
+*
+* // app/routes/issue.tsx: one function for both, since React Router
+* // removes `loader` from the browser's bundle.
+* export const loader = load
+* export const clientLoader = load
+* ```
+*
+* @stability unstable
+* @category integrations
+* @since 0.2.0
+*/
+const clientAtomsMiddleware = (context) => (args, next) => {
+	const registry = current();
+	if (registry === void 0) throw new Error("clientAtomsMiddleware found no mounted RegistryProvider: render raf-effect-atom/react-router's RegistryProvider around the app in the root layout.");
+	args.context.set(context, browserAtomsOf(registry));
+	return next();
+};
+export { RegistryProvider, atomsMiddleware, clientAtomsMiddleware };

package/dist/RegistryProvider.d.mts

@@ -18,6 +18,9 @@ import * as React from "react";
  * It's read once, when the registry is made. The server's request registry
  * lives for one request, so it has none.
  *
+ * In the browser, React Router's `clientAtomsMiddleware` gives client
+ * loaders the registry of the mounted provider.
+ *
  * **Example**
  *
  * ```tsx

package/dist/RegistryProvider.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { make } from "./internal/registry.mjs";
+import { make, mount } from "./internal/registry.mjs";
 import { RegistryContext } from "@effect/atom-react";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
@@ -29,6 +29,9 @@ import { jsx } from "react/jsx-runtime";
 * It's read once, when the registry is made. The server's request registry
 * lives for one request, so it has none.
 *
+* In the browser, React Router's `clientAtomsMiddleware` gives client
+* loaders the registry of the mounted provider.
+*
 * **Example**
 *
 * ```tsx
@@ -47,6 +50,7 @@ import { jsx } from "react/jsx-runtime";
 */
 const RegistryProvider = (props) => {
 	const [registry] = React.useState(() => make({ defaultIdleTTL: props.defaultIdleTTL }));
+	React.useEffect(() => mount(registry), [registry]);
 	return /* @__PURE__ */ jsx(RegistryContext.Provider, {
 		value: registry,
 		children: props.children

package/dist/internal/registry.mjs

@@ -13,4 +13,18 @@ const make = (options) => isServer() ? make$1({ seed: options?.seed }) : AtomReg
 	defaultIdleTTL: options?.defaultIdleTTL ?? defaultIdleTTL,
 	scheduleTask
 });
-export { isServer, make };
+let mounted;
+/**
+* Records the browser registry a `RegistryProvider` provides while it's
+* mounted, for code outside React, such as React Router's client
+* middleware. Returns the cleanup that forgets it.
+*/
+const mount = (registry) => {
+	mounted = registry;
+	return () => {
+		if (mounted === registry) mounted = void 0;
+	};
+};
+/** The browser registry of the mounted `RegistryProvider`, if one is. */
+const current = () => mounted;
+export { current, isServer, make, mount };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Render-as-you-fetch for Effect Atom: start atoms from route loaders and stream them into the browser, typed failures intact",
   "keywords": [
     "effect",
@@ -58,7 +58,7 @@
     "@types/react-dom": "19.3.0",
     "@vitest/coverage-v8": "5.0.5",
     "effect": "4.0.6",
-    "effect-atom-boundary": "0.1.0",
+    "effect-atom-boundary": "0.1.1",
     "happy-dom": "21.0.4",
     "react": "19.3.1",
     "react-dom": "19.3.1",