@btst/stack 3.0.0-rc.1 → 3.0.0-rc.2

package/dist/tanstack/index.d.cts

@@ -1,4 +1,4 @@
-import { S as StackRequestHandler, G as GetStackClient } from '../shared/stack.DrUBX-QE.cjs';
+import { S as StackRequestHandler, G as GetStackClient, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { QueryClient } from '@tanstack/react-query';
 import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.cjs';
@@ -38,9 +38,23 @@ declare function toTanStackHandlers(handler: StackRequestHandler): {
     }) => Response | Promise<Response>;
 };
 
-interface CreateTanStackPageOptions {
+interface TanStackPageLoaderArgs<TContext = unknown> {
+    /** Parameters for the TanStack catch-all route. */
+    params: {
+        _splat?: string;
+    };
+    /** The current TanStack router context. */
+    context: TContext;
+}
+interface CreateTanStackPageOptions<TContext = unknown> {
     /** Returns the stack client for a given QueryClient (`lib/stack-client`). */
     getStackClient: GetStackClient;
+    /**
+     * Resolves the stack client for the isomorphic route loader. Use an
+     * isomorphic adapter when request-aware setup differs on the server and
+     * client. Defaults to `getStackClient`.
+     */
+    getLoaderStackClient?: ResolveStackClient<TanStackPageLoaderArgs<TContext>>;
     /**
      * Returns the QueryClient for the current context. Defaults to the
      * `queryClient` from the router context (set up by
@@ -48,12 +62,6 @@ interface CreateTanStackPageOptions {
      */
     getQueryClient?: () => QueryClient;
 }
-interface TanStackPageLoaderArgs {
-    params: {
-        _splat?: string;
-    };
-    context?: unknown;
-}
 /**
  * Creates the route options for the TanStack Start catch-all page, to spread
  * into `createFileRoute("/pages/$")(...)`: SSR prefetch via `route.loader()`,
@@ -73,10 +81,10 @@ interface TanStackPageLoaderArgs {
  * );
  * ```
  */
-declare function createTanStackPageOptions(options: CreateTanStackPageOptions): {
+declare function createTanStackPageOptions<TContext = unknown>(options: CreateTanStackPageOptions<TContext>): {
     readonly ssr: true;
     readonly component: () => react_jsx_runtime.JSX.Element;
-    readonly loader: ({ params, context }: TanStackPageLoaderArgs) => Promise<{
+    readonly loader: (loaderArgs: TanStackPageLoaderArgs<TContext>) => Promise<{
         meta: any;
     }>;
     readonly head: ({ loaderData }: {
@@ -106,5 +114,5 @@ declare function createTanStackPageOptions(options: CreateTanStackPageOptions):
  */
 declare function tanstackRouter(): StackRouterConfig;
 
-export { GetStackClient, StackRequestHandler, createTanStackPageOptions, tanstackRouter, toTanStackHandlers };
-export type { CreateTanStackPageOptions };
+export { GetStackClient, ResolveStackClient, StackRequestHandler, createTanStackPageOptions, tanstackRouter, toTanStackHandlers };
+export type { CreateTanStackPageOptions, TanStackPageLoaderArgs };

package/dist/tanstack/index.d.mts

@@ -1,4 +1,4 @@
-import { S as StackRequestHandler, G as GetStackClient } from '../shared/stack.DrUBX-QE.mjs';
+import { S as StackRequestHandler, G as GetStackClient, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { QueryClient } from '@tanstack/react-query';
 import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.mjs';
@@ -38,9 +38,23 @@ declare function toTanStackHandlers(handler: StackRequestHandler): {
     }) => Response | Promise<Response>;
 };
 
-interface CreateTanStackPageOptions {
+interface TanStackPageLoaderArgs<TContext = unknown> {
+    /** Parameters for the TanStack catch-all route. */
+    params: {
+        _splat?: string;
+    };
+    /** The current TanStack router context. */
+    context: TContext;
+}
+interface CreateTanStackPageOptions<TContext = unknown> {
     /** Returns the stack client for a given QueryClient (`lib/stack-client`). */
     getStackClient: GetStackClient;
+    /**
+     * Resolves the stack client for the isomorphic route loader. Use an
+     * isomorphic adapter when request-aware setup differs on the server and
+     * client. Defaults to `getStackClient`.
+     */
+    getLoaderStackClient?: ResolveStackClient<TanStackPageLoaderArgs<TContext>>;
     /**
      * Returns the QueryClient for the current context. Defaults to the
      * `queryClient` from the router context (set up by
@@ -48,12 +62,6 @@ interface CreateTanStackPageOptions {
      */
     getQueryClient?: () => QueryClient;
 }
-interface TanStackPageLoaderArgs {
-    params: {
-        _splat?: string;
-    };
-    context?: unknown;
-}
 /**
  * Creates the route options for the TanStack Start catch-all page, to spread
  * into `createFileRoute("/pages/$")(...)`: SSR prefetch via `route.loader()`,
@@ -73,10 +81,10 @@ interface TanStackPageLoaderArgs {
  * );
  * ```
  */
-declare function createTanStackPageOptions(options: CreateTanStackPageOptions): {
+declare function createTanStackPageOptions<TContext = unknown>(options: CreateTanStackPageOptions<TContext>): {
     readonly ssr: true;
     readonly component: () => react_jsx_runtime.JSX.Element;
-    readonly loader: ({ params, context }: TanStackPageLoaderArgs) => Promise<{
+    readonly loader: (loaderArgs: TanStackPageLoaderArgs<TContext>) => Promise<{
         meta: any;
     }>;
     readonly head: ({ loaderData }: {
@@ -106,5 +114,5 @@ declare function createTanStackPageOptions(options: CreateTanStackPageOptions):
  */
 declare function tanstackRouter(): StackRouterConfig;
 
-export { GetStackClient, StackRequestHandler, createTanStackPageOptions, tanstackRouter, toTanStackHandlers };
-export type { CreateTanStackPageOptions };
+export { GetStackClient, ResolveStackClient, StackRequestHandler, createTanStackPageOptions, tanstackRouter, toTanStackHandlers };
+export type { CreateTanStackPageOptions, TanStackPageLoaderArgs };

package/dist/tanstack/index.d.ts

@@ -1,4 +1,4 @@
-import { S as StackRequestHandler, G as GetStackClient } from '../shared/stack.DrUBX-QE.js';
+import { S as StackRequestHandler, G as GetStackClient, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { QueryClient } from '@tanstack/react-query';
 import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.js';
@@ -38,9 +38,23 @@ declare function toTanStackHandlers(handler: StackRequestHandler): {
     }) => Response | Promise<Response>;
 };
 
-interface CreateTanStackPageOptions {
+interface TanStackPageLoaderArgs<TContext = unknown> {
+    /** Parameters for the TanStack catch-all route. */
+    params: {
+        _splat?: string;
+    };
+    /** The current TanStack router context. */
+    context: TContext;
+}
+interface CreateTanStackPageOptions<TContext = unknown> {
     /** Returns the stack client for a given QueryClient (`lib/stack-client`). */
     getStackClient: GetStackClient;
+    /**
+     * Resolves the stack client for the isomorphic route loader. Use an
+     * isomorphic adapter when request-aware setup differs on the server and
+     * client. Defaults to `getStackClient`.
+     */
+    getLoaderStackClient?: ResolveStackClient<TanStackPageLoaderArgs<TContext>>;
     /**
      * Returns the QueryClient for the current context. Defaults to the
      * `queryClient` from the router context (set up by
@@ -48,12 +62,6 @@ interface CreateTanStackPageOptions {
      */
     getQueryClient?: () => QueryClient;
 }
-interface TanStackPageLoaderArgs {
-    params: {
-        _splat?: string;
-    };
-    context?: unknown;
-}
 /**
  * Creates the route options for the TanStack Start catch-all page, to spread
  * into `createFileRoute("/pages/$")(...)`: SSR prefetch via `route.loader()`,
@@ -73,10 +81,10 @@ interface TanStackPageLoaderArgs {
  * );
  * ```
  */
-declare function createTanStackPageOptions(options: CreateTanStackPageOptions): {
+declare function createTanStackPageOptions<TContext = unknown>(options: CreateTanStackPageOptions<TContext>): {
     readonly ssr: true;
     readonly component: () => react_jsx_runtime.JSX.Element;
-    readonly loader: ({ params, context }: TanStackPageLoaderArgs) => Promise<{
+    readonly loader: (loaderArgs: TanStackPageLoaderArgs<TContext>) => Promise<{
         meta: any;
     }>;
     readonly head: ({ loaderData }: {
@@ -106,5 +114,5 @@ declare function createTanStackPageOptions(options: CreateTanStackPageOptions):
  */
 declare function tanstackRouter(): StackRouterConfig;
 
-export { GetStackClient, StackRequestHandler, createTanStackPageOptions, tanstackRouter, toTanStackHandlers };
-export type { CreateTanStackPageOptions };
+export { GetStackClient, ResolveStackClient, StackRequestHandler, createTanStackPageOptions, tanstackRouter, toTanStackHandlers };
+export type { CreateTanStackPageOptions, TanStackPageLoaderArgs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "3.0.0-rc.1",
+  "version": "3.0.0-rc.2",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -833,7 +833,7 @@
     }
   },
   "dependencies": {
-    "@btst/db": "2.2.2",
+    "@btst/db": "2.2.3",
     "@milkdown/crepe": "^7.17.1",
     "@milkdown/kit": "^7.17.1",
     "remend": "^1.0.1",
@@ -843,7 +843,7 @@
     "@ai-sdk/react": ">=2.0.0",
     "@aws-sdk/client-s3": ">=3.0.0",
     "@aws-sdk/s3-request-presigner": ">=3.0.0",
-    "@btst/yar": ">=1.3.0",
+    "@btst/yar": ">=1.3.2",
     "@hookform/resolvers": ">=5.0.0",
     "@radix-ui/react-dialog": ">=1.1.0",
     "@radix-ui/react-label": ">=2.1.0",
@@ -854,7 +854,7 @@
     "@tanstack/react-router": ">=1.0.0",
     "@vercel/blob": ">=0.14.0",
     "ai": ">=5.0.0",
-    "better-call": ">=1.3.5",
+    "better-call": "1.3.6",
     "class-variance-authority": ">=0.7.0",
     "clsx": ">=2.1.0",
     "cmdk": ">=1.1.0",
@@ -903,8 +903,8 @@
     "@ai-sdk/react": "^2.0.94",
     "@aws-sdk/client-s3": "^3.1011.0",
     "@aws-sdk/s3-request-presigner": "^3.1011.0",
-    "@btst/adapter-memory": "2.2.2",
-    "@btst/yar": "1.3.0",
+    "@btst/adapter-memory": "2.2.3",
+    "@btst/yar": "1.3.2",
     "@tanstack/react-router": "1.168.10",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/src/__tests__/entry-factories.test.tsx

@@ -23,6 +23,14 @@ function makeQueryClient() {
 	});
 }
 
+function reactRouterLoaderArgs(splat: string) {
+	return {
+		request: new Request(`http://test.local/${splat}`),
+		params: { "*": splat },
+		context: undefined,
+	};
+}
+
 const okHandler = async (request: Request) =>
 	new Response(`ok:${request.method}`);
 
@@ -96,6 +104,28 @@ describe("createNextPage", () => {
 		expect(html).toContain("blog page");
 	});
 
+	it("supports an async request-aware stack client when rendering", async () => {
+		const queryClient = makeQueryClient();
+		const pageProps = { params: params(["account"]) };
+		const page = createNextPage({
+			getStackClient: async (currentQueryClient, currentPageProps) => {
+				const { all } = await currentPageProps.params;
+				return makeStackClient({
+					[`/${all?.join("/")}`]: {
+						PageComponent: () => <div>request-aware page</div>,
+					},
+				})(currentQueryClient);
+			},
+			getQueryClient: () => queryClient,
+		});
+
+		const element = await page.Page(pageProps);
+		const html = renderToString(
+			<QueryClientProvider client={queryClient}>{element}</QueryClientProvider>,
+		);
+		expect(html).toContain("request-aware page");
+	});
+
 	it("calls notFound when no route matches", async () => {
 		const notFound = vi.fn(() => {
 			throw new Error("NEXT_NOT_FOUND_TEST");
@@ -140,6 +170,26 @@ describe("createNextPage", () => {
 		});
 	});
 
+	it("generateMetadata awaits a request-aware stack client", async () => {
+		const page = createNextPage({
+			getStackClient: async (queryClient, { params: pageParams }) => {
+				const { all } = await pageParams;
+				return makeStackClient({
+					[`/${all?.join("/")}`]: {
+						meta: () => [{ name: "title", content: "Request Metadata" }],
+					},
+				})(queryClient);
+			},
+			getQueryClient: makeQueryClient,
+		});
+
+		const metadata = await page.generateMetadata({
+			params: params(["account"]),
+		});
+
+		expect(metadata).toMatchObject({ title: "Request Metadata" });
+	});
+
 	it("generateMetadata returns {} without running the loader when the route has no meta", async () => {
 		const loader = vi.fn();
 		const page = createNextPage({
@@ -170,6 +220,35 @@ describe("createNextPage", () => {
 });
 
 describe("createReactRouterPage", () => {
+	it("creates an async request-aware loader without changing the render client", async () => {
+		const queryClient = makeQueryClient();
+		const page = createReactRouterPage({
+			getStackClient: makeStackClient({}),
+			getQueryClient: () => queryClient,
+		});
+		const loader = page.createLoader<{ role: string }>(
+			async (currentQueryClient, { request, context }) => {
+				const role = context.role;
+				const requestRole = request.headers.get("x-role");
+				return makeStackClient({
+					"/account": {
+						meta: () => [{ name: "viewer", content: `${role}:${requestRole}` }],
+					},
+				})(currentQueryClient);
+			},
+		);
+
+		const data = await loader({
+			params: { "*": "account" },
+			request: new Request("http://test.local/account", {
+				headers: { "x-role": "member" },
+			}),
+			context: { role: "admin" },
+		});
+
+		expect(data.meta).toEqual([{ name: "viewer", content: "admin:member" }]);
+	});
+
 	it("loader prefetches and returns path, dehydratedState and meta", async () => {
 		const queryClient = makeQueryClient();
 		const page = createReactRouterPage({
@@ -187,7 +266,7 @@ describe("createReactRouterPage", () => {
 			getQueryClient: () => queryClient,
 		});
 
-		const data = await page.loader({ params: { "*": "blog" } });
+		const data = await page.loader(reactRouterLoaderArgs("blog"));
 		expect(data.path).toBe("/blog");
 		expect(data.meta).toEqual([{ name: "title", content: "Blog" }]);
 		expect(data.dehydratedState.queries).toHaveLength(1);
@@ -215,7 +294,7 @@ describe("createReactRouterPage", () => {
 			getQueryClient: () => queryClient,
 		});
 
-		const data = await page.loader({ params: { "*": "broken" } });
+		const data = await page.loader(reactRouterLoaderArgs("broken"));
 		const errored = data.dehydratedState.queries.find(
 			(q) => q.state.status === "error",
 		);
@@ -244,12 +323,33 @@ describe("createReactRouterPage", () => {
 		});
 
 		expect(page.ErrorBoundary).toBe(CustomErrorBoundary);
-		const data = await page.loader({ params: { "*": "broken" } });
+		const data = await page.loader(reactRouterLoaderArgs("broken"));
 		expect(data.dehydratedState.queries).toHaveLength(0);
 	});
 });
 
 describe("createTanStackPageOptions", () => {
+	it("awaits a context-aware stack client for isomorphic loaders", async () => {
+		const queryClient = makeQueryClient();
+		const options = createTanStackPageOptions<{ role: string }>({
+			getStackClient: makeStackClient({}),
+			getQueryClient: () => queryClient,
+			getLoaderStackClient: async (currentQueryClient, { context }) =>
+				makeStackClient({
+					"/account": {
+						meta: () => [{ title: `Account for ${context.role}` }],
+					},
+				})(currentQueryClient),
+		});
+
+		const data = await options.loader({
+			params: { _splat: "account" },
+			context: { role: "admin" },
+		});
+
+		expect(data).toEqual({ meta: [{ title: "Account for admin" }] });
+	});
+
 	it("loader throws notFound() when no route matches", async () => {
 		const options = createTanStackPageOptions({
 			getStackClient: makeStackClient({}),
@@ -257,7 +357,7 @@ describe("createTanStackPageOptions", () => {
 		});
 
 		await expect(
-			options.loader({ params: { _splat: "missing" } }),
+			options.loader({ params: { _splat: "missing" }, context: undefined }),
 		).rejects.toMatchObject({ isNotFound: true });
 	});
 

package/src/__tests__/package-metadata.test.ts

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+describe("published dependency alignment", () => {
+	it("uses the Better DB release that shares the Better Auth 1.6.16 cohort", async () => {
+		const manifest = JSON.parse(
+			await readFile(resolve("package.json"), "utf8"),
+		) as {
+			dependencies?: Record<string, string>;
+			devDependencies?: Record<string, string>;
+			peerDependencies?: Record<string, string>;
+		};
+
+		expect(manifest.dependencies?.["@btst/db"]).toBe("2.2.3");
+		expect(manifest.devDependencies?.["@btst/adapter-memory"]).toBe("2.2.3");
+		expect(manifest.devDependencies?.["@btst/yar"]).toBe("1.3.2");
+		expect(manifest.peerDependencies?.["@btst/yar"]).toBe(">=1.3.2");
+		expect(manifest.peerDependencies?.["better-call"]).toBe("1.3.6");
+	});
+});

package/src/next/index.tsx

@@ -1,11 +1,13 @@
 export { toNextRouteHandlers } from "./handlers";
 export {
 	type CreateNextPageOptions,
+	type GetNextStackClient,
 	type NextPageProps,
 	createNextPage,
 } from "./page";
 export { nextRouter } from "./router";
 export type {
 	GetStackClient,
+	ResolveStackClient,
 	StackRequestHandler,
 } from "../shared/entry-factories";

package/src/next/page.tsx

@@ -6,7 +6,7 @@ import type { ReactNode } from "react";
 import { metaElementsToObject } from "../client/meta-utils";
 import { normalizePath } from "../client/path-utils";
 import {
-	type GetStackClient,
+	type ResolveStackClient,
 	stackDehydrateOptions,
 } from "../shared/entry-factories";
 
@@ -14,9 +14,15 @@ export interface NextPageProps {
 	params: Promise<{ all?: string[] }>;
 }
 
+/** Resolves the stack client for a Next.js page or metadata request. */
+export type GetNextStackClient = ResolveStackClient<NextPageProps>;
+
 export interface CreateNextPageOptions {
-	/** Returns the stack client for a given QueryClient (`lib/stack-client`). */
-	getStackClient: GetStackClient;
+	/**
+	 * Returns the stack client for the current request. May be async and receives
+	 * the page props so request-aware clients can resolve request-local state.
+	 */
+	getStackClient: GetNextStackClient;
 	/** Returns the QueryClient for the current context (`lib/query-client`). */
 	getQueryClient: () => QueryClient;
 	/**
@@ -63,11 +69,13 @@ export function createNextPage(options: CreateNextPageOptions) {
 		dehydrateOptions = stackDehydrateOptions,
 	} = options;
 
-	async function Page({ params }: NextPageProps) {
+	async function Page(pageProps: NextPageProps) {
+		const { params } = pageProps;
 		const pathParams = await params;
 		const path = normalizePath(pathParams?.all);
 		const queryClient = getQueryClient();
-		const route = getStackClient(queryClient).router.getRoute(path);
+		const stackClient = await getStackClient(queryClient, pageProps);
+		const route = stackClient.router.getRoute(path);
 
 		if (route?.loader) {
 			await route.loader();
@@ -82,13 +90,13 @@ export function createNextPage(options: CreateNextPageOptions) {
 		);
 	}
 
-	async function generateMetadata({
-		params,
-	}: NextPageProps): Promise<Metadata> {
+	async function generateMetadata(pageProps: NextPageProps): Promise<Metadata> {
+		const { params } = pageProps;
 		const pathParams = await params;
 		const path = normalizePath(pathParams?.all);
 		const queryClient = getQueryClient();
-		const route = getStackClient(queryClient).router.getRoute(path);
+		const stackClient = await getStackClient(queryClient, pageProps);
+		const route = stackClient.router.getRoute(path);
 
 		if (!route) {
 			return notFound();

package/src/plugins/comments/__tests__/client-sweep.test.tsx

@@ -496,6 +496,29 @@ describe("CommentThread provider wiring", () => {
 				?.getAttribute("href"),
 		).toBe("/sign-in");
 	});
+
+	it("prefers the per-thread login href when unauthenticated", async () => {
+		await render(
+			<StackProvider
+				basePath="/pages"
+				api={{ baseURL: "http://provider.local", basePath: "/api/stack" }}
+				auth={{ getIdentity: () => null, loginPath: "/sign-in" }}
+			>
+				<CommentThread
+					resourceId="post-1"
+					resourceType="blog-post"
+					loginHref="/sign-in?redirectTo=%2Fblog%2Fpost-1%23comments"
+				/>
+			</StackProvider>,
+		);
+		await act(async () => {});
+
+		expect(
+			container
+				.querySelector<HTMLAnchorElement>('[data-testid="login-link"]')
+				?.getAttribute("href"),
+		).toBe("/sign-in?redirectTo=%2Fblog%2Fpost-1%23comments");
+	});
 });
 
 describe("CommentForm inline field errors (StackError)", () => {

package/src/plugins/comments/client/components/comment-thread.tsx

@@ -69,6 +69,11 @@ export interface CommentThreadProps {
 	className?: string;
 	/** Localization strings — defaults to English */
 	localization?: Partial<CommentsLocalization>;
+	/**
+	 * Sign-in URL for unauthenticated users in this thread.
+	 * Overrides the `loginPath` from the nearest `StackProvider`.
+	 */
+	loginHref?: string;
 	/**
 	 * Number of top-level comments to load per page.
 	 * Clicking "Load more" fetches the next page. Default: 10.
@@ -103,7 +108,6 @@ type ResolvedCommentThreadProps = CommentThreadProps & {
 	apiBaseURL: string;
 	apiBasePath: string;
 	currentUserId?: string;
-	loginHref?: string;
 };
 
 const DEFAULT_RENDERER: ComponentType<CommentRendererProps> = ({ body }) => (
@@ -842,7 +846,7 @@ export function CommentThread(props: CommentThreadProps) {
 		apiBaseURL: api?.baseURL ?? "",
 		apiBasePath: api?.basePath ?? "",
 		currentUserId,
-		loginHref: auth?.loginPath,
+		loginHref: props.loginHref ?? auth?.loginPath,
 	};
 
 	return (

package/src/react-router/index.tsx

@@ -7,5 +7,6 @@ export {
 export { reactRouter } from "./router";
 export type {
 	GetStackClient,
+	ResolveStackClient,
 	StackRequestHandler,
 } from "../shared/entry-factories";

package/src/react-router/page.tsx

@@ -10,6 +10,7 @@ import { useLoaderData, useRouteError } from "react-router";
 import { normalizePath } from "../client/path-utils";
 import {
 	type GetStackClient,
+	type ResolveStackClient,
 	stackDehydrateOptions,
 } from "../shared/entry-factories";
 
@@ -19,8 +20,13 @@ import {
  * are not available inside the library, so the factory types the subset it
  * uses; the results remain assignable to the generated route exports.
  */
-export interface ReactRouterPageLoaderArgs {
+export interface ReactRouterPageLoaderArgs<TContext = unknown> {
+	/** The request that triggered the route loader. */
+	request: Request;
+	/** Parameters for the React Router catch-all route. */
 	params: { "*"?: string } & Record<string, string | undefined>;
+	/** Request-local values supplied by React Router middleware. */
+	context: TContext;
 }
 
 export interface CreateReactRouterPageOptions {
@@ -75,22 +81,37 @@ export function createReactRouterPage(options: CreateReactRouterPageOptions) {
 		dehydrateOptions = stackDehydrateOptions,
 	} = options;
 
-	async function loader({ params }: ReactRouterPageLoaderArgs) {
-		const queryClient = getQueryClient();
-		const path = normalizePath(params["*"]);
-		const route = getStackClient(queryClient).router.getRoute(path);
+	/** Creates a loader with an optional async, request-aware stack client. */
+	function createLoader<TContext = unknown>(
+		getLoaderStackClient?: ResolveStackClient<
+			ReactRouterPageLoaderArgs<TContext>
+		>,
+	) {
+		return async function loader(
+			loaderArgs: ReactRouterPageLoaderArgs<TContext>,
+		) {
+			const { params } = loaderArgs;
+			const queryClient = getQueryClient();
+			const path = normalizePath(params["*"]);
+			const stackClient = getLoaderStackClient
+				? await getLoaderStackClient(queryClient, loaderArgs)
+				: getStackClient(queryClient);
+			const route = stackClient.router.getRoute(path);
 
-		if (route?.loader) {
-			await route.loader();
-		}
+			if (route?.loader) {
+				await route.loader();
+			}
 
-		return {
-			path,
-			dehydratedState: dehydrate(queryClient, dehydrateOptions),
-			meta: await route?.meta?.(),
+			return {
+				path,
+				dehydratedState: dehydrate(queryClient, dehydrateOptions),
+				meta: await route?.meta?.(),
+			};
 		};
 	}
 
+	const loader = createLoader();
+
 	type LoaderData = Awaited<ReturnType<typeof loader>>;
 
 	// Recent React Router versions pass `loaderData`; older 7.x used `data`.
@@ -132,6 +153,7 @@ export function createReactRouterPage(options: CreateReactRouterPageOptions) {
 
 	return {
 		loader,
+		createLoader,
 		meta,
 		Component,
 		ErrorBoundary: CustomErrorBoundary ?? DefaultErrorBoundary,

package/src/shared/entry-factories.ts

@@ -35,6 +35,15 @@ export interface StackClientLike {
  */
 export type GetStackClient = (queryClient: QueryClient) => StackClientLike;
 
+/**
+ * Consumer-provided resolver for lifecycle phases that can await request-aware
+ * stack client creation.
+ */
+export type ResolveStackClient<TContext> = (
+	queryClient: QueryClient,
+	context: TContext,
+) => StackClientLike | PromiseLike<StackClientLike>;
+
 /**
  * A framework-agnostic BTST API handler, as returned by
  * `createBackendHandler(...).handler`.