@btst/stack 2.9.2 → 2.9.4

package/src/plugins/comments/client/plugin.tsx

@@ -2,10 +2,14 @@
 import { lazy } from "react";
 import {
 	defineClientPlugin,
+	createApiClient,
 	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
+import type { CommentsApiRouter } from "../api";
+import { createCommentsQueryKeys } from "../query-keys";
+import { createSanitizedSSRLoaderError } from "../../utils";
 
 // Lazy load page components for code splitting
 const ModerationPageComponent = lazy(() =>
@@ -36,6 +40,11 @@ export interface LoaderContext {
 	apiBasePath: string;
 	/** Optional headers for the request */
 	headers?: Headers;
+	/**
+	 * Optional current user ID for SSR loaders that need user-scoped query keys.
+	 * Hooks (e.g. beforeLoadUserComments) may populate this.
+	 */
+	currentUserId?: string;
 	/** Additional context properties */
 	[key: string]: unknown;
 }
@@ -81,7 +90,7 @@ export interface CommentsClientConfig {
 function createModerationLoader(config: CommentsClientConfig) {
 	return async () => {
 		if (typeof window === "undefined") {
-			const { apiBasePath, apiBaseURL, headers, hooks } = config;
+			const { queryClient, apiBasePath, apiBaseURL, headers, hooks } = config;
 			const context: LoaderContext = {
 				path: "/comments/moderation",
 				isSSR: true,
@@ -89,15 +98,43 @@ function createModerationLoader(config: CommentsClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<CommentsApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCommentsQueryKeys(client, headers);
+			const listQuery = queries.comments.list({
+				status: "pending",
+				limit: 20,
+				offset: 0,
+			});
 			try {
 				if (hooks?.beforeLoadModeration) {
 					await hooks.beforeLoadModeration(context);
 				}
+				await queryClient.prefetchQuery(listQuery);
+				const queryState = queryClient.getQueryState(listQuery.queryKey);
+				if (queryState?.error && hooks?.onLoadError) {
+					const error =
+						queryState.error instanceof Error
+							? queryState.error
+							: new Error(String(queryState.error));
+					await hooks.onLoadError(error, context);
+				}
 			} catch (error) {
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/comments] route.loader() failed — no server running at build time.",
 					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: listQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
 				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
@@ -110,7 +147,7 @@ function createModerationLoader(config: CommentsClientConfig) {
 function createUserCommentsLoader(config: CommentsClientConfig) {
 	return async () => {
 		if (typeof window === "undefined") {
-			const { apiBasePath, apiBaseURL, headers, hooks } = config;
+			const { queryClient, apiBasePath, apiBaseURL, headers, hooks } = config;
 			const context: LoaderContext = {
 				path: "/comments",
 				isSSR: true,
@@ -118,15 +155,58 @@ function createUserCommentsLoader(config: CommentsClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<CommentsApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCommentsQueryKeys(client, headers);
+			const getUserListQuery = (currentUserId: string) =>
+				queries.comments.list({
+					authorId: currentUserId,
+					sort: "desc",
+					limit: 20,
+					offset: 0,
+				});
 			try {
 				if (hooks?.beforeLoadUserComments) {
 					await hooks.beforeLoadUserComments(context);
 				}
+				const currentUserId =
+					typeof context.currentUserId === "string"
+						? context.currentUserId
+						: undefined;
+				if (currentUserId) {
+					const listQuery = getUserListQuery(currentUserId);
+					await queryClient.prefetchQuery(listQuery);
+					const queryState = queryClient.getQueryState(listQuery.queryKey);
+					if (queryState?.error && hooks?.onLoadError) {
+						const error =
+							queryState.error instanceof Error
+								? queryState.error
+								: new Error(String(queryState.error));
+						await hooks.onLoadError(error, context);
+					}
+				}
 			} catch (error) {
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/comments] route.loader() failed — no server running at build time.",
 					);
+				} else {
+					const currentUserId =
+						typeof context.currentUserId === "string"
+							? context.currentUserId
+							: undefined;
+					if (currentUserId) {
+						const errToStore = createSanitizedSSRLoaderError();
+						await queryClient.prefetchQuery({
+							queryKey: getUserListQuery(currentUserId).queryKey,
+							queryFn: () => {
+								throw errToStore;
+							},
+							retry: false,
+						});
+					}
 				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);

package/src/plugins/comments/client/utils.ts

@@ -1,5 +1,6 @@
 import { useState, useEffect } from "react";
 import type { CommentsPluginOverrides } from "./overrides";
+import { toError as toErrorShared } from "../error-utils";
 
 /**
  * Resolves `currentUserId` from the plugin overrides, supporting both a static
@@ -40,20 +41,7 @@ export function useResolvedCurrentUserId(
  *    copied onto the Error via Object.assign so callers can inspect them.
  * 3. Anything else — converted via String().
  */
-export function toError(error: unknown): Error {
-	if (error instanceof Error) return error;
-	if (typeof error === "object" && error !== null) {
-		const obj = error as Record<string, unknown>;
-		const message =
-			(typeof obj.message === "string" ? obj.message : null) ||
-			(typeof obj.error === "string" ? obj.error : null) ||
-			JSON.stringify(error);
-		const err = new Error(message);
-		Object.assign(err, error);
-		return err;
-	}
-	return new Error(String(error));
-}
+export const toError = toErrorShared;
 
 export function getInitials(name: string | null | undefined): string {
 	if (!name) return "?";

package/src/plugins/comments/error-utils.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize any thrown value into an Error.
+ */
+export function toError(error: unknown): Error {
+	if (error instanceof Error) return error;
+	if (typeof error === "object" && error !== null) {
+		const obj = error as Record<string, unknown>;
+		const message =
+			(typeof obj.message === "string" ? obj.message : null) ||
+			(typeof obj.error === "string" ? obj.error : null) ||
+			JSON.stringify(error);
+		const err = new Error(message);
+		Object.assign(err, error);
+		return err;
+	}
+	return new Error(String(error));
+}

package/src/plugins/comments/query-keys.ts

@@ -10,7 +10,7 @@ import {
 	commentCountDiscriminator,
 	commentsThreadDiscriminator,
 } from "./api/query-key-defs";
-import { toError } from "./client/utils";
+import { toError } from "./error-utils";
 
 interface CommentsListParams {
 	resourceId?: string;

package/src/plugins/form-builder/client/plugin.tsx

@@ -9,6 +9,7 @@ import {
 import { createRoute } from "@btst/yar";
 import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
+import { createSanitizedSSRLoaderError } from "../../utils";
 import type { FormBuilderApiRouter } from "../api";
 import { createFormBuilderQueryKeys } from "../query-keys";
 
@@ -160,6 +161,13 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<FormBuilderApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createFormBuilderQueryKeys(client, headers);
+			const limit = 20;
+			const listQuery = queries.forms.list({ limit, offset: 0 });
 
 			try {
 				// Before hook - authorization check
@@ -170,15 +178,7 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 					);
 				}
 
-				const client = createApiClient<FormBuilderApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createFormBuilderQueryKeys(client, headers);
-				const limit = 20;
-
 				// Prefetch forms using infinite query
-				const listQuery = queries.forms.list({ limit, offset: 0 });
 				await queryClient.prefetchInfiniteQuery({
 					queryKey: listQuery.queryKey,
 					queryFn: async ({ pageParam = 0 }) => {
@@ -221,6 +221,16 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 						"[btst/form-builder] route.loader() failed — no server running at build time. " +
 							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
 					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchInfiniteQuery({
+						queryKey: listQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						initialPageParam: 0,
+						retry: false,
+					});
 				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
@@ -249,6 +259,12 @@ function createFormBuilderLoader(
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<FormBuilderApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createFormBuilderQueryKeys(client, headers);
+			const formQuery = id ? queries.forms.byId(id) : undefined;
 
 			try {
 				// Before hook - authorization check
@@ -259,15 +275,9 @@ function createFormBuilderLoader(
 					);
 				}
 
-				const client = createApiClient<FormBuilderApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createFormBuilderQueryKeys(client, headers);
-
 				// Prefetch form if editing
 				if (id) {
-					await queryClient.prefetchQuery(queries.forms.byId(id));
+					await queryClient.prefetchQuery(formQuery!);
 				}
 
 				// After hook
@@ -277,9 +287,7 @@ function createFormBuilderLoader(
 
 				// Check if there was an error
 				if (id) {
-					const queryState = queryClient.getQueryState(
-						queries.forms.byId(id).queryKey,
-					);
+					const queryState = queryClient.getQueryState(formQuery!.queryKey);
 					if (queryState?.error && hooks?.onLoadError) {
 						const error =
 							queryState.error instanceof Error
@@ -295,6 +303,15 @@ function createFormBuilderLoader(
 						"[btst/form-builder] route.loader() failed — no server running at build time. " +
 							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
 					);
+				} else if (formQuery) {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: formQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
 				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
@@ -323,6 +340,18 @@ function createSubmissionsLoader(
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<FormBuilderApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createFormBuilderQueryKeys(client, headers);
+			const limit = 20;
+			const formQuery = queries.forms.byId(formId);
+			const submissionsQuery = queries.formSubmissions.list({
+				formId,
+				limit,
+				offset: 0,
+			});
 
 			try {
 				// Before hook - authorization check
@@ -333,21 +362,8 @@ function createSubmissionsLoader(
 					);
 				}
 
-				const client = createApiClient<FormBuilderApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createFormBuilderQueryKeys(client, headers);
-				const limit = 20;
-
 				// Prefetch form and submissions
-				await queryClient.prefetchQuery(queries.forms.byId(formId));
-
-				const submissionsQuery = queries.formSubmissions.list({
-					formId,
-					limit,
-					offset: 0,
-				});
+				await queryClient.prefetchQuery(formQuery);
 				await queryClient.prefetchInfiniteQuery({
 					queryKey: submissionsQuery.queryKey,
 					queryFn: async ({ pageParam = 0 }) => {
@@ -379,9 +395,7 @@ function createSubmissionsLoader(
 				}
 
 				// Check if there was an error
-				const formState = queryClient.getQueryState(
-					queries.forms.byId(formId).queryKey,
-				);
+				const formState = queryClient.getQueryState(formQuery.queryKey);
 				const submissionsState = queryClient.getQueryState(
 					submissionsQuery.queryKey,
 				);
@@ -400,6 +414,16 @@ function createSubmissionsLoader(
 						"[btst/form-builder] route.loader() failed — no server running at build time. " +
 							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
 					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchInfiniteQuery({
+						queryKey: submissionsQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						initialPageParam: 0,
+						retry: false,
+					});
 				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);

package/src/plugins/media/__tests__/plugin.test.ts

@@ -84,14 +84,14 @@ function createVercelBlobStorageAdapter(
 	return {
 		type: "vercel-blob",
 		urlHostnameSuffix: ".public.blob.vercel-storage.com",
-		handleRequest: vi.fn(async (request, callbacks) => {
-			const body = (await request.json()) as {
+		handleRequest: vi.fn(async (request, body, callbacks) => {
+			const parsedBody = (body ?? ((await request.json()) as unknown)) as {
 				pathname?: string;
 				clientPayload?: string | null;
 			};
 			const tokenOptions = await callbacks.onBeforeGenerateToken?.(
-				body.pathname ?? "photo.jpg",
-				body.clientPayload ?? null,
+				parsedBody.pathname ?? "photo.jpg",
+				parsedBody.clientPayload ?? null,
 			);
 			return { ok: true, tokenOptions };
 		}),

package/src/plugins/media/db.ts

@@ -31,6 +31,10 @@ export const mediaSchema = createDbPlugin("media", {
 			folderId: {
 				type: "string",
 				required: false,
+				references: {
+					model: "mediaFolder",
+					field: "id",
+				},
 			},
 			alt: {
 				type: "string",
@@ -52,6 +56,10 @@ export const mediaSchema = createDbPlugin("media", {
 			parentId: {
 				type: "string",
 				required: false,
+				references: {
+					model: "mediaFolder",
+					field: "id",
+				},
 			},
 			createdAt: {
 				type: "date",

package/src/plugins/ui-builder/client/plugin.tsx

@@ -3,6 +3,7 @@ import { lazy } from "react";
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
@@ -10,6 +11,7 @@ import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { CMSApiRouter } from "../../cms/api";
 import { createCMSQueryKeys } from "../../cms/query-keys";
+import { createSanitizedSSRLoaderError } from "../../utils";
 import { UI_BUILDER_TYPE_SLUG } from "../schemas";
 import type {
 	UIBuilderClientHooks,
@@ -81,6 +83,18 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+			const limit = 20;
+			const listQuery = queries.cmsContent.list({
+				typeSlug,
+				limit,
+				offset: 0,
+			});
+			const uiBuilderListQueryKey = [...listQuery.queryKey, "ui-builder"];
 
 			try {
 				// Before hook - authorization check
@@ -91,21 +105,9 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 					);
 				}
 
-				const client = createApiClient<CMSApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createCMSQueryKeys(client, headers);
-				const limit = 20;
-
 				// Prefetch pages using infinite query
-				const listQuery = queries.cmsContent.list({
-					typeSlug,
-					limit,
-					offset: 0,
-				});
 				await queryClient.prefetchInfiniteQuery({
-					queryKey: [...listQuery.queryKey, "ui-builder"],
+					queryKey: uiBuilderListQueryKey,
 					queryFn: async ({ pageParam = 0 }) => {
 						const response: unknown = await client("/content/:typeSlug", {
 							method: "GET",
@@ -133,8 +135,7 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 
 				// Check if there was an error
 				const queryState = queryClient.getQueryState([
-					...listQuery.queryKey,
-					"ui-builder",
+					...uiBuilderListQueryKey,
 				]);
 				if (queryState?.error && hooks?.onLoadError) {
 					const error =
@@ -145,6 +146,22 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/ui-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.uiBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchInfiniteQuery({
+						queryKey: uiBuilderListQueryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						initialPageParam: 0,
+						retry: false,
+					});
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -173,6 +190,14 @@ function createPageBuilderLoader(
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+			const pageQuery = id
+				? queries.cmsContent.detail(typeSlug, id)
+				: undefined;
 
 			try {
 				// Before hook - authorization check
@@ -183,17 +208,9 @@ function createPageBuilderLoader(
 					);
 				}
 
-				const client = createApiClient<CMSApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createCMSQueryKeys(client, headers);
-
 				// Prefetch page if editing
 				if (id) {
-					await queryClient.prefetchQuery(
-						queries.cmsContent.detail(typeSlug, id),
-					);
+					await queryClient.prefetchQuery(pageQuery!);
 				}
 
 				// After hook
@@ -203,9 +220,7 @@ function createPageBuilderLoader(
 
 				// Check if there was an error
 				if (id) {
-					const queryState = queryClient.getQueryState(
-						queries.cmsContent.detail(typeSlug, id).queryKey,
-					);
+					const queryState = queryClient.getQueryState(pageQuery!.queryKey);
 					if (queryState?.error && hooks?.onLoadError) {
 						const error =
 							queryState.error instanceof Error
@@ -216,6 +231,21 @@ function createPageBuilderLoader(
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/ui-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.uiBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				} else if (pageQuery) {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: pageQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}

package/src/plugins/utils.ts

@@ -109,6 +109,24 @@ export function isConnectionError(err: unknown): boolean {
 		code === "ERR_CONNECTION_REFUSED"
 	);
 }
+
+/**
+ * Public-safe message used when SSR loader failures are intentionally seeded
+ * into React Query so Error Boundaries can render on the client.
+ *
+ * Never include raw server error text here because dehydrated query state can
+ * be serialized into HTML.
+ */
+export const SSR_LOADER_ERROR_MESSAGE = "Failed to load data.";
+
+/**
+ * Creates a sanitized Error for SSR loader cache seeding.
+ *
+ * Use this instead of storing raw server errors in dehydrated query state.
+ */
+export function createSanitizedSSRLoaderError(): Error {
+	return new Error(SSR_LOADER_ERROR_MESSAGE);
+}
 import type { Router, Endpoint, Status, statusCodes } from "better-call";
 
 interface CreateApiClientOptions {