@btst/stack 2.9.3 → 2.9.4

package/dist/packages/stack/src/plugins/ui-builder/client/plugin.mjs

@@ -1,8 +1,9 @@
 import { jsx } from 'react/jsx-runtime';
 import { lazy } from 'react';
-import { defineClientPlugin, createApiClient, runClientHookWithShim } from '@btst/stack/plugins/client';
+import { defineClientPlugin, createApiClient, runClientHookWithShim, isConnectionError } from '@btst/stack/plugins/client';
 import { createRoute } from '@btst/yar';
 import { createCMSQueryKeys } from '../../../../../../plugins/cms/query-keys.mjs';
+import { createSanitizedSSRLoaderError } from '../../utils.mjs';
 import { UI_BUILDER_TYPE_SLUG } from '../schemas.mjs';
 
 const PageListPageComponent = lazy(
@@ -27,6 +28,18 @@ function createPageListLoader(config) {
         apiBasePath,
         headers
       };
+      const client = createApiClient({
+        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 {
         if (hooks?.beforeLoadPageList) {
           await runClientHookWithShim(
@@ -34,19 +47,8 @@ function createPageListLoader(config) {
             "Load prevented by beforeLoadPageList hook"
           );
         }
-        const client = createApiClient({
-          baseURL: apiBaseURL,
-          basePath: apiBasePath
-        });
-        const queries = createCMSQueryKeys(client, headers);
-        const limit = 20;
-        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 = await client("/content/:typeSlug", {
               method: "GET",
@@ -65,14 +67,28 @@ function createPageListLoader(config) {
           await hooks.afterLoadPageList(context);
         }
         const queryState = queryClient.getQueryState([
-          ...listQuery.queryKey,
-          "ui-builder"
+          ...uiBuilderListQueryKey
         ]);
         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/ui-builder] route.loader() failed \u2014 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, context);
         }
@@ -93,6 +109,12 @@ function createPageBuilderLoader(id, config) {
         apiBasePath,
         headers
       };
+      const client = createApiClient({
+        baseURL: apiBaseURL,
+        basePath: apiBasePath
+      });
+      const queries = createCMSQueryKeys(client, headers);
+      const pageQuery = id ? queries.cmsContent.detail(typeSlug, id) : void 0;
       try {
         if (hooks?.beforeLoadPageBuilder) {
           await runClientHookWithShim(
@@ -100,29 +122,34 @@ function createPageBuilderLoader(id, config) {
             "Load prevented by beforeLoadPageBuilder hook"
           );
         }
-        const client = createApiClient({
-          baseURL: apiBaseURL,
-          basePath: apiBasePath
-        });
-        const queries = createCMSQueryKeys(client, headers);
         if (id) {
-          await queryClient.prefetchQuery(
-            queries.cmsContent.detail(typeSlug, id)
-          );
+          await queryClient.prefetchQuery(pageQuery);
         }
         if (hooks?.afterLoadPageBuilder) {
           await hooks.afterLoadPageBuilder(id, context);
         }
         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 ? queryState.error : new Error(String(queryState.error));
             await hooks.onLoadError(error, context);
           }
         }
       } catch (error) {
+        if (isConnectionError(error)) {
+          console.warn(
+            "[btst/ui-builder] route.loader() failed \u2014 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, context);
         }

package/dist/packages/stack/src/plugins/utils.cjs

@@ -47,6 +47,10 @@ function isConnectionError(err) {
   const code = err.cause?.code ?? err.code;
   return err.message.includes("ECONNREFUSED") || err.message.includes("fetch failed") || err.message.includes("ERR_CONNECTION_REFUSED") || code === "ECONNREFUSED" || code === "ERR_CONNECTION_REFUSED";
 }
+const SSR_LOADER_ERROR_MESSAGE = "Failed to load data.";
+function createSanitizedSSRLoaderError() {
+  return new Error(SSR_LOADER_ERROR_MESSAGE);
+}
 function createApiClient(options) {
   const { baseURL = "", basePath = "/" } = options ?? {};
   const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
@@ -58,7 +62,9 @@ function createApiClient(options) {
   });
 }
 
+exports.SSR_LOADER_ERROR_MESSAGE = SSR_LOADER_ERROR_MESSAGE;
 exports.createApiClient = createApiClient;
+exports.createSanitizedSSRLoaderError = createSanitizedSSRLoaderError;
 exports.isConnectionError = isConnectionError;
 exports.runClientHookWithShim = runClientHookWithShim;
 exports.runHookWithShim = runHookWithShim;

package/dist/packages/stack/src/plugins/utils.mjs

@@ -45,6 +45,10 @@ function isConnectionError(err) {
   const code = err.cause?.code ?? err.code;
   return err.message.includes("ECONNREFUSED") || err.message.includes("fetch failed") || err.message.includes("ERR_CONNECTION_REFUSED") || code === "ECONNREFUSED" || code === "ERR_CONNECTION_REFUSED";
 }
+const SSR_LOADER_ERROR_MESSAGE = "Failed to load data.";
+function createSanitizedSSRLoaderError() {
+  return new Error(SSR_LOADER_ERROR_MESSAGE);
+}
 function createApiClient(options) {
   const { baseURL = "", basePath = "/" } = options ?? {};
   const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
@@ -56,4 +60,4 @@ function createApiClient(options) {
   });
 }
 
-export { createApiClient, isConnectionError, runClientHookWithShim, runHookWithShim };
+export { SSR_LOADER_ERROR_MESSAGE, createApiClient, createSanitizedSSRLoaderError, isConnectionError, runClientHookWithShim, runHookWithShim };

package/dist/plugins/client/index.cjs

@@ -8,7 +8,9 @@ function defineClientPlugin(plugin) {
   return plugin;
 }
 
+exports.SSR_LOADER_ERROR_MESSAGE = utils.SSR_LOADER_ERROR_MESSAGE;
 exports.createApiClient = utils.createApiClient;
+exports.createSanitizedSSRLoaderError = utils.createSanitizedSSRLoaderError;
 exports.isConnectionError = utils.isConnectionError;
 exports.runClientHookWithShim = utils.runClientHookWithShim;
 exports.createRoute = yar.createRoute;

package/dist/plugins/client/index.d.cts

@@ -20,6 +20,20 @@ declare function runClientHookWithShim<T>(hookFn: () => Promise<T> | T, defaultM
  * `route.loader()` is called during `next build` with no HTTP server running.
  */
 declare function isConnectionError(err: unknown): boolean;
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare function createSanitizedSSRLoaderError(): Error;
 
 interface CreateApiClientOptions {
     baseURL?: string;
@@ -67,4 +81,4 @@ declare function createApiClient<TRouter extends Router | Record<string, Endpoin
  */
 declare function defineClientPlugin<TOverrides = Record<string, never>, TRoutes extends Record<string, Route> = Record<string, Route>>(plugin: ClientPlugin<TOverrides, TRoutes>): ClientPlugin<TOverrides, TRoutes>;
 
-export { ClientPlugin, createApiClient, defineClientPlugin, isConnectionError, runClientHookWithShim };
+export { ClientPlugin, SSR_LOADER_ERROR_MESSAGE, createApiClient, createSanitizedSSRLoaderError, defineClientPlugin, isConnectionError, runClientHookWithShim };

package/dist/plugins/client/index.d.mts

@@ -20,6 +20,20 @@ declare function runClientHookWithShim<T>(hookFn: () => Promise<T> | T, defaultM
  * `route.loader()` is called during `next build` with no HTTP server running.
  */
 declare function isConnectionError(err: unknown): boolean;
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare function createSanitizedSSRLoaderError(): Error;
 
 interface CreateApiClientOptions {
     baseURL?: string;
@@ -67,4 +81,4 @@ declare function createApiClient<TRouter extends Router | Record<string, Endpoin
  */
 declare function defineClientPlugin<TOverrides = Record<string, never>, TRoutes extends Record<string, Route> = Record<string, Route>>(plugin: ClientPlugin<TOverrides, TRoutes>): ClientPlugin<TOverrides, TRoutes>;
 
-export { ClientPlugin, createApiClient, defineClientPlugin, isConnectionError, runClientHookWithShim };
+export { ClientPlugin, SSR_LOADER_ERROR_MESSAGE, createApiClient, createSanitizedSSRLoaderError, defineClientPlugin, isConnectionError, runClientHookWithShim };

package/dist/plugins/client/index.d.ts

@@ -20,6 +20,20 @@ declare function runClientHookWithShim<T>(hookFn: () => Promise<T> | T, defaultM
  * `route.loader()` is called during `next build` with no HTTP server running.
  */
 declare function isConnectionError(err: unknown): boolean;
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare function createSanitizedSSRLoaderError(): Error;
 
 interface CreateApiClientOptions {
     baseURL?: string;
@@ -67,4 +81,4 @@ declare function createApiClient<TRouter extends Router | Record<string, Endpoin
  */
 declare function defineClientPlugin<TOverrides = Record<string, never>, TRoutes extends Record<string, Route> = Record<string, Route>>(plugin: ClientPlugin<TOverrides, TRoutes>): ClientPlugin<TOverrides, TRoutes>;
 
-export { ClientPlugin, createApiClient, defineClientPlugin, isConnectionError, runClientHookWithShim };
+export { ClientPlugin, SSR_LOADER_ERROR_MESSAGE, createApiClient, createSanitizedSSRLoaderError, defineClientPlugin, isConnectionError, runClientHookWithShim };

package/dist/plugins/client/index.mjs

@@ -1,4 +1,4 @@
-export { createApiClient, isConnectionError, runClientHookWithShim } from '../../packages/stack/src/plugins/utils.mjs';
+export { SSR_LOADER_ERROR_MESSAGE, createApiClient, createSanitizedSSRLoaderError, isConnectionError, runClientHookWithShim } from '../../packages/stack/src/plugins/utils.mjs';
 export { createRoute, createRouter } from '@btst/yar';
 export { createClient } from 'better-call/client';
 

package/dist/plugins/comments/client/index.d.cts

@@ -21,6 +21,11 @@ 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;
 }

package/dist/plugins/comments/client/index.d.mts

@@ -21,6 +21,11 @@ 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;
 }

package/dist/plugins/comments/client/index.d.ts

@@ -21,6 +21,11 @@ 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;
 }

package/dist/plugins/comments/query-keys.cjs

@@ -2,7 +2,7 @@
 
 const queryKeyFactory = require('@lukemorales/query-key-factory');
 const queryKeyDefs = require('../../packages/stack/src/plugins/comments/api/query-key-defs.cjs');
-const utils = require('../../packages/stack/src/plugins/comments/client/utils.cjs');
+const errorUtils = require('../../packages/stack/src/plugins/comments/error-utils.cjs');
 
 function isErrorResponse(response) {
   return typeof response === "object" && response !== null && "error" in response && response.error !== null && response.error !== void 0;
@@ -40,7 +40,7 @@ function createCommentsQueries(client, headers) {
           headers
         });
         if (isErrorResponse(response)) {
-          throw utils.toError(response.error);
+          throw errorUtils.toError(response.error);
         }
         const data = response.data;
         return data ?? { items: [], total: 0, limit: 20, offset: 0 };
@@ -63,7 +63,7 @@ function createCommentCountQueries(client, headers) {
           headers
         });
         if (isErrorResponse(response)) {
-          throw utils.toError(response.error);
+          throw errorUtils.toError(response.error);
         }
         const data = response.data;
         return data?.count ?? 0;
@@ -96,7 +96,7 @@ function createCommentsThreadQueries(client, headers) {
           headers
         });
         if (isErrorResponse(response)) {
-          throw utils.toError(response.error);
+          throw errorUtils.toError(response.error);
         }
         const data = response.data;
         return data ?? {

package/dist/plugins/comments/query-keys.mjs

@@ -1,6 +1,6 @@
 import { mergeQueryKeys, createQueryKeys } from '@lukemorales/query-key-factory';
 import { commentsListDiscriminator, commentCountDiscriminator, commentsThreadDiscriminator } from '../../packages/stack/src/plugins/comments/api/query-key-defs.mjs';
-import { toError } from '../../packages/stack/src/plugins/comments/client/utils.mjs';
+import { toError } from '../../packages/stack/src/plugins/comments/error-utils.mjs';
 
 function isErrorResponse(response) {
   return typeof response === "object" && response !== null && "error" in response && response.error !== null && response.error !== void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.9.3",
+  "version": "2.9.4",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",