@btst/stack 2.9.2 → 2.9.4

package/src/__tests__/client-plugin-ssr-loaders.test.ts

@@ -0,0 +1,329 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { QueryClient } from "@tanstack/react-query";
+import { createApiClient, SSR_LOADER_ERROR_MESSAGE } from "../plugins/client";
+import { blogClientPlugin } from "../plugins/blog/client";
+import type { BlogApiRouter } from "../plugins/blog/api";
+import { createBlogQueryKeys } from "../plugins/blog/query-keys";
+import { cmsClientPlugin } from "../plugins/cms/client";
+import type { CMSApiRouter } from "../plugins/cms/api";
+import { createCMSQueryKeys } from "../plugins/cms/query-keys";
+import { formBuilderClientPlugin } from "../plugins/form-builder/client";
+import type { FormBuilderApiRouter } from "../plugins/form-builder/api";
+import { createFormBuilderQueryKeys } from "../plugins/form-builder/query-keys";
+import { uiBuilderClientPlugin } from "../plugins/ui-builder/client";
+import { UI_BUILDER_TYPE_SLUG } from "../plugins/ui-builder";
+import { commentsClientPlugin } from "../plugins/comments/client";
+import type { CommentsApiRouter } from "../plugins/comments/api";
+import { createCommentsQueryKeys } from "../plugins/comments/query-keys";
+
+const API_BASE_URL = "http://localhost:3000";
+const API_BASE_PATH = "/api/data";
+const SITE_BASE_URL = "http://localhost:3000";
+const SITE_BASE_PATH = "/pages";
+const TEST_HEADERS = new Headers();
+
+function getErrorMessage(
+	queryClient: QueryClient,
+	queryKey: readonly unknown[],
+) {
+	const error = queryClient.getQueryState(queryKey)?.error;
+	return error instanceof Error ? error.message : null;
+}
+
+function mockFetchApiError(errorMessage: string) {
+	return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+		new Response(JSON.stringify({ message: errorMessage }), {
+			status: 500,
+			headers: { "content-type": "application/json" },
+		}),
+	);
+}
+
+describe("client plugin SSR loaders", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("blog drafts loader seeds query error when beforeLoadPosts throws", async () => {
+		const queryClient = new QueryClient();
+		const expectedError = new Error("blog drafts blocked");
+
+		const plugin = blogClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadPosts: () => {
+					throw expectedError;
+				},
+			},
+		});
+
+		const route = plugin.routes().drafts();
+		await route.loader?.();
+
+		const client = createApiClient<BlogApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const queries = createBlogQueryKeys(client, TEST_HEADERS);
+		const listQuery = queries.posts.list({
+			query: undefined,
+			limit: 10,
+			published: false,
+		});
+
+		expect(getErrorMessage(queryClient, listQuery.queryKey)).toBe(
+			SSR_LOADER_ERROR_MESSAGE,
+		);
+	});
+
+	it("cms content list loader seeds query error when beforeLoadContentList throws", async () => {
+		const queryClient = new QueryClient();
+		const expectedError = new Error("cms list blocked");
+		const typeSlug = "article";
+
+		const plugin = cmsClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadContentList: () => {
+					throw expectedError;
+				},
+			},
+		});
+
+		const route = plugin.routes().contentList({ params: { typeSlug } });
+		await route.loader?.();
+
+		const client = createApiClient<CMSApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const queries = createCMSQueryKeys(client, TEST_HEADERS);
+		const listQuery = queries.cmsContent.list({
+			typeSlug,
+			limit: 20,
+			offset: 0,
+		});
+
+		expect(getErrorMessage(queryClient, listQuery.queryKey)).toBe(
+			SSR_LOADER_ERROR_MESSAGE,
+		);
+	});
+
+	it("form list loader seeds query error when beforeLoadFormList throws", async () => {
+		const queryClient = new QueryClient();
+		const expectedError = new Error("form list blocked");
+
+		const plugin = formBuilderClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadFormList: () => {
+					throw expectedError;
+				},
+			},
+		});
+
+		const route = plugin.routes().formList();
+		await route.loader?.();
+
+		const client = createApiClient<FormBuilderApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const queries = createFormBuilderQueryKeys(client, TEST_HEADERS);
+		const listQuery = queries.forms.list({ limit: 20, offset: 0 });
+
+		expect(getErrorMessage(queryClient, listQuery.queryKey)).toBe(
+			SSR_LOADER_ERROR_MESSAGE,
+		);
+	});
+
+	it("ui-builder list loader seeds query error when beforeLoadPageList throws", async () => {
+		const queryClient = new QueryClient();
+		const expectedError = new Error("ui-builder list blocked");
+
+		const plugin = uiBuilderClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			componentRegistry: {},
+			hooks: {
+				beforeLoadPageList: () => {
+					throw expectedError;
+				},
+			},
+		});
+
+		const route = plugin.routes().pageList();
+		await route.loader?.();
+
+		const client = createApiClient<CMSApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const queries = createCMSQueryKeys(client, TEST_HEADERS);
+		const listQuery = queries.cmsContent.list({
+			typeSlug: UI_BUILDER_TYPE_SLUG,
+			limit: 20,
+			offset: 0,
+		});
+		const uiBuilderQueryKey = [...listQuery.queryKey, "ui-builder"] as const;
+
+		expect(getErrorMessage(queryClient, uiBuilderQueryKey)).toBe(
+			SSR_LOADER_ERROR_MESSAGE,
+		);
+	});
+
+	it("comments moderation loader seeds query error when beforeLoadModeration throws", async () => {
+		const queryClient = new QueryClient();
+		const expectedError = new Error("comments moderation blocked");
+
+		const plugin = commentsClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadModeration: () => {
+					throw expectedError;
+				},
+			},
+		});
+
+		const route = plugin.routes().moderation();
+		await route.loader?.();
+
+		const client = createApiClient<CommentsApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const queries = createCommentsQueryKeys(client, TEST_HEADERS);
+		const listQuery = queries.comments.list({
+			status: "pending",
+			limit: 20,
+			offset: 0,
+		});
+
+		expect(getErrorMessage(queryClient, listQuery.queryKey)).toBe(
+			SSR_LOADER_ERROR_MESSAGE,
+		);
+	});
+
+	it("comments user loader seeds query error with user-scoped key when beforeLoadUserComments throws", async () => {
+		const queryClient = new QueryClient();
+		const expectedError = new Error("comments user view blocked");
+		const currentUserId = "user-123";
+
+		const plugin = commentsClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadUserComments: (context) => {
+					context.currentUserId = currentUserId;
+					throw expectedError;
+				},
+			},
+		});
+
+		const route = plugin.routes().userComments();
+		await route.loader?.();
+
+		const client = createApiClient<CommentsApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const queries = createCommentsQueryKeys(client, TEST_HEADERS);
+		const listQuery = queries.comments.list({
+			authorId: currentUserId,
+			sort: "desc",
+			limit: 20,
+			offset: 0,
+		});
+
+		expect(getErrorMessage(queryClient, listQuery.queryKey)).toBe(
+			SSR_LOADER_ERROR_MESSAGE,
+		);
+	});
+
+	it("comments moderation loader calls onLoadError when prefetch stores API error", async () => {
+		const queryClient = new QueryClient();
+		const apiErrorMessage = "comments moderation api failed";
+		const onLoadError = vi.fn();
+		mockFetchApiError(apiErrorMessage);
+
+		const plugin = commentsClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				onLoadError,
+			},
+		});
+
+		const route = plugin.routes().moderation();
+		await route.loader?.();
+
+		expect(onLoadError).toHaveBeenCalledTimes(1);
+		const [errorArg] = onLoadError.mock.calls[0] ?? [];
+		expect(errorArg).toBeInstanceOf(Error);
+		expect((errorArg as Error).message).toBe(apiErrorMessage);
+	});
+
+	it("comments user loader calls onLoadError when user-scoped prefetch stores API error", async () => {
+		const queryClient = new QueryClient();
+		const apiErrorMessage = "comments user api failed";
+		const onLoadError = vi.fn();
+		const currentUserId = "user-123";
+		mockFetchApiError(apiErrorMessage);
+
+		const plugin = commentsClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadUserComments: (context) => {
+					context.currentUserId = currentUserId;
+				},
+				onLoadError,
+			},
+		});
+
+		const route = plugin.routes().userComments();
+		await route.loader?.();
+
+		expect(onLoadError).toHaveBeenCalledTimes(1);
+		const [errorArg, contextArg] = onLoadError.mock.calls[0] ?? [];
+		expect(errorArg).toBeInstanceOf(Error);
+		expect((errorArg as Error).message).toBe(apiErrorMessage);
+		expect(contextArg).toMatchObject({ currentUserId });
+	});
+});

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

@@ -7,6 +7,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 { BlogApiRouter } from "../api";
 import { createBlogQueryKeys } from "../query-keys";
 import type { Post, SerializedPost, SerializedTag } from "../types";
@@ -183,6 +184,18 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const limit = 10;
+			const client = createApiClient<BlogApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			// note: for a module not to be bundled with client, and to be shared by client and server we need to add it to build.config.ts as an entry
+			const queries = createBlogQueryKeys(client, headers);
+			const listQuery = queries.posts.list({
+				query: undefined,
+				limit,
+				published: published,
+			});
 
 			try {
 				// Before hook
@@ -193,20 +206,6 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 					);
 				}
 
-				const limit = 10;
-				const client = createApiClient<BlogApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-
-				// note: for a module not to be bundled with client, and to be shared by client and server we need to add it to build.config.ts as an entry
-				const queries = createBlogQueryKeys(client, headers);
-				const listQuery = queries.posts.list({
-					query: undefined,
-					limit,
-					published: published,
-				});
-
 				await queryClient.prefetchInfiniteQuery({
 					...listQuery,
 					initialPageParam: 0,
@@ -250,6 +249,16 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 						"[btst/blog] route.loader() failed — no server running at build time. " +
 							"Use myStack.api.blog.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);

package/src/plugins/client/index.ts

@@ -20,8 +20,10 @@ export type {
 
 export {
 	createApiClient,
+	createSanitizedSSRLoaderError,
 	isConnectionError,
 	runClientHookWithShim,
+	SSR_LOADER_ERROR_MESSAGE,
 } from "../utils";
 
 // Re-export Yar types needed for plugins

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

@@ -8,6 +8,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 { CMSApiRouter } from "../api";
 import { createCMSQueryKeys } from "../query-keys";
 
@@ -163,6 +164,12 @@ function createDashboardLoader(config: CMSClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+			const typesQuery = queries.cmsTypes.list();
 
 			try {
 				// Before hook - authorization check
@@ -173,13 +180,7 @@ function createDashboardLoader(config: CMSClientConfig) {
 					);
 				}
 
-				const client = createApiClient<CMSApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createCMSQueryKeys(client, headers);
-
-				await queryClient.prefetchQuery(queries.cmsTypes.list());
+				await queryClient.prefetchQuery(typesQuery);
 
 				// After hook
 				if (hooks?.afterLoadDashboard) {
@@ -187,9 +188,7 @@ function createDashboardLoader(config: CMSClientConfig) {
 				}
 
 				// Check if there was an error
-				const queryState = queryClient.getQueryState(
-					queries.cmsTypes.list().queryKey,
-				);
+				const queryState = queryClient.getQueryState(typesQuery.queryKey);
 				if (queryState?.error && hooks?.onLoadError) {
 					const error =
 						queryState.error instanceof Error
@@ -205,6 +204,15 @@ function createDashboardLoader(config: CMSClientConfig) {
 						"[btst/cms] route.loader() failed — no server running at build time. " +
 							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
 					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: typesQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
 				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
@@ -231,6 +239,18 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+			const limit = 20;
+			const typesQuery = queries.cmsTypes.list();
+			const listQuery = queries.cmsContent.list({
+				typeSlug,
+				limit,
+				offset: 0,
+			});
 
 			try {
 				// Before hook - authorization check
@@ -241,22 +261,10 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 					);
 				}
 
-				const client = createApiClient<CMSApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createCMSQueryKeys(client, headers);
-				const limit = 20;
-
 				// Prefetch content types
-				await queryClient.prefetchQuery(queries.cmsTypes.list());
+				await queryClient.prefetchQuery(typesQuery);
 
 				// Prefetch content list using infinite query (matches useSuspenseInfiniteQuery in hooks)
-				const listQuery = queries.cmsContent.list({
-					typeSlug,
-					limit,
-					offset: 0,
-				});
 				await queryClient.prefetchInfiniteQuery({
 					queryKey: listQuery.queryKey,
 					queryFn: async ({ pageParam = 0 }) => {
@@ -285,9 +293,7 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 				}
 
 				// Check if there was an error in either query
-				const typesState = queryClient.getQueryState(
-					queries.cmsTypes.list().queryKey,
-				);
+				const typesState = queryClient.getQueryState(typesQuery.queryKey);
 				const listState = queryClient.getQueryState(listQuery.queryKey);
 				const queryError = typesState?.error || listState?.error;
 				if (queryError && hooks?.onLoadError) {
@@ -305,6 +311,16 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 						"[btst/cms] route.loader() failed — no server running at build time. " +
 							"Use myStack.api.cms.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);
@@ -335,6 +351,15 @@ function createContentEditorLoader(
 				apiBasePath,
 				headers,
 			};
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+			const typesQuery = queries.cmsTypes.list();
+			const detailQuery = id
+				? queries.cmsContent.detail(typeSlug, id)
+				: undefined;
 
 			try {
 				// Before hook - authorization check
@@ -345,17 +370,9 @@ function createContentEditorLoader(
 					);
 				}
 
-				const client = createApiClient<CMSApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-				const queries = createCMSQueryKeys(client, headers);
-
-				const promises = [queryClient.prefetchQuery(queries.cmsTypes.list())];
+				const promises = [queryClient.prefetchQuery(typesQuery)];
 				if (id) {
-					promises.push(
-						queryClient.prefetchQuery(queries.cmsContent.detail(typeSlug, id)),
-					);
+					promises.push(queryClient.prefetchQuery(detailQuery!));
 				}
 				await Promise.all(promises);
 
@@ -365,13 +382,9 @@ function createContentEditorLoader(
 				}
 
 				// Check if there was an error
-				const typesState = queryClient.getQueryState(
-					queries.cmsTypes.list().queryKey,
-				);
+				const typesState = queryClient.getQueryState(typesQuery.queryKey);
 				const itemState = id
-					? queryClient.getQueryState(
-							queries.cmsContent.detail(typeSlug, id).queryKey,
-						)
+					? queryClient.getQueryState(detailQuery!.queryKey)
 					: null;
 				const queryError = typesState?.error || itemState?.error;
 				if (queryError && hooks?.onLoadError) {
@@ -389,6 +402,24 @@ function createContentEditorLoader(
 						"[btst/cms] route.loader() failed — no server running at build time. " +
 							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
 					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: typesQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
+					if (detailQuery) {
+						await queryClient.prefetchQuery({
+							queryKey: detailQuery.queryKey,
+							queryFn: () => {
+								throw errToStore;
+							},
+							retry: false,
+						});
+					}
 				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);