@btst/stack 2.2.0 → 2.3.0

package/dist/shared/stack.snB1EDP7.d.cts

@@ -0,0 +1,419 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
+import { createApiClient } from '@btst/stack/plugins/client';
+import { P as Post, T as Tag, c as createPostSchema, u as updatePostSchema, S as SerializedPost, a as SerializedTag } from './stack.CBON0dWL.cjs';
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import * as better_call from 'better-call';
+import { Adapter } from '@btst/db';
+import { z } from 'zod';
+
+/**
+ * Parameters for filtering/paginating posts.
+ * Mirrors the shape of the list API query schema.
+ */
+interface PostListParams {
+    slug?: string;
+    tagSlug?: string;
+    offset?: number;
+    limit?: number;
+    query?: string;
+    published?: boolean;
+}
+/**
+ * Paginated result returned by {@link getAllPosts}.
+ */
+interface PostListResult {
+    items: Array<Post & {
+        tags: Tag[];
+    }>;
+    total: number;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Retrieve all posts matching optional filter criteria.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks (e.g. `onBeforeListPosts`) are NOT
+ * called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param params - Optional filter/pagination parameters (same shape as the list API query)
+ */
+declare function getAllPosts(adapter: Adapter, params?: PostListParams): Promise<PostListResult>;
+/**
+ * Retrieve a single post by its slug, including associated tags.
+ * Returns null if no post is found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param slug - The post slug
+ */
+declare function getPostBySlug(adapter: Adapter, slug: string): Promise<(Post & {
+    tags: Tag[];
+}) | null>;
+/**
+ * Retrieve all tags, sorted alphabetically by name.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ */
+declare function getAllTags(adapter: Adapter): Promise<Tag[]>;
+
+/**
+ * Route keys for the blog plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+type BlogRouteKey = "posts" | "drafts" | "post" | "tag" | "newPost" | "editPost";
+/**
+ * Overloaded signature for `prefetchForRoute`.
+ * TypeScript enforces the correct params for each routeKey at call sites.
+ */
+interface BlogPrefetchForRoute {
+    (key: "posts" | "drafts" | "newPost", qc: QueryClient): Promise<void>;
+    (key: "post" | "editPost", qc: QueryClient, params: {
+        slug: string;
+    }): Promise<void>;
+    (key: "tag", qc: QueryClient, params: {
+        tagSlug: string;
+    }): Promise<void>;
+}
+declare const PostListQuerySchema: z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    tagSlug: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    query: z.ZodOptional<z.ZodString>;
+    published: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean | undefined, string | undefined>>;
+}, z.core.$strip>;
+declare const NextPreviousPostsQuerySchema: z.ZodObject<{
+    date: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+/**
+ * Context passed to blog API hooks
+ */
+interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
+    body?: TBody;
+    params?: TParams;
+    query?: TQuery;
+    request?: Request;
+    headers?: Headers;
+    [key: string]: any;
+}
+/**
+ * Configuration hooks for blog backend plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface BlogBackendHooks {
+    /**
+     * Called before listing posts. Return false to deny access.
+     * @param filter - Query parameters for filtering posts
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeListPosts?: (filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before creating a post. Return false to deny access.
+     * @param data - Post data being created
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeCreatePost?: (data: z.infer<typeof createPostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a post. Return false to deny access.
+     * @param postId - ID of the post being updated
+     * @param data - Updated post data
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeUpdatePost?: (postId: string, data: z.infer<typeof updatePostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a post. Return false to deny access.
+     * @param postId - ID of the post being deleted
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeDeletePost?: (postId: string, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after posts are read successfully
+     * @param posts - The list of posts returned by the query
+     * @param filter - Query parameters used for filtering
+     * @param context - Request context
+     */
+    onPostsRead?: (posts: Array<Post & {
+        tags: Tag[];
+    }>, filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is created successfully
+     * @param post - The created post
+     * @param context - Request context
+     */
+    onPostCreated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is updated successfully
+     * @param post - The updated post
+     * @param context - Request context
+     */
+    onPostUpdated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is deleted successfully
+     * @param postId - ID of the deleted post
+     * @param context - Request context
+     */
+    onPostDeleted?: (postId: string, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when listing posts fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onListPostsError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when creating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onCreatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when updating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onUpdatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when deleting a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onDeletePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+}
+/**
+ * Blog backend plugin
+ * Provides API endpoints for managing blog posts
+ * Uses better-db adapter for database operations
+ *
+ * @param hooks - Optional configuration hooks for customizing plugin behavior
+ */
+declare const blogBackendPlugin: (hooks?: BlogBackendHooks) => _btst_stack_plugins_api.BackendPlugin<{
+    readonly listPosts: better_call.StrictEndpoint<"/posts", {
+        method: "GET";
+        query: z.ZodObject<{
+            slug: z.ZodOptional<z.ZodString>;
+            tagSlug: z.ZodOptional<z.ZodString>;
+            offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+            limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+            query: z.ZodOptional<z.ZodString>;
+            published: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean | undefined, string | undefined>>;
+        }, z.core.$strip>;
+    }, PostListResult>;
+    readonly createPost: better_call.StrictEndpoint<"/posts", {
+        method: "POST";
+        body: z.ZodObject<{
+            tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                slug: z.ZodString;
+            }, z.core.$strip>]>>>>;
+            slug: z.ZodOptional<z.ZodString>;
+            publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            title: z.ZodString;
+            content: z.ZodString;
+            excerpt: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+            published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        }, z.core.$strip>;
+    }, Post>;
+    readonly updatePost: better_call.StrictEndpoint<"/posts/:id", {
+        method: "PUT";
+        body: z.ZodObject<{
+            publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            title: z.ZodString;
+            content: z.ZodString;
+            excerpt: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+            published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            slug: z.ZodString;
+            tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                slug: z.ZodString;
+            }, z.core.$strip>]>>>>;
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, Post>;
+    readonly deletePost: better_call.StrictEndpoint<"/posts/:id", {
+        method: "DELETE";
+    }, {
+        success: boolean;
+    }>;
+    readonly getNextPreviousPosts: better_call.StrictEndpoint<"/posts/next-previous", {
+        method: "GET";
+        query: z.ZodObject<{
+            date: z.ZodCoercedDate<unknown>;
+        }, z.core.$strip>;
+    }, {
+        previous: {
+            tags: Tag[];
+            id: string;
+            authorId?: string;
+            defaultLocale?: string;
+            slug: string;
+            title: string;
+            content: string;
+            excerpt: string;
+            image?: string;
+            published: boolean;
+            status?: "DRAFT" | "PUBLISHED";
+            publishedAt?: Date;
+            createdAt: Date;
+            updatedAt: Date;
+        } | null;
+        next: {
+            tags: Tag[];
+            id: string;
+            authorId?: string;
+            defaultLocale?: string;
+            slug: string;
+            title: string;
+            content: string;
+            excerpt: string;
+            image?: string;
+            published: boolean;
+            status?: "DRAFT" | "PUBLISHED";
+            publishedAt?: Date;
+            createdAt: Date;
+            updatedAt: Date;
+        } | null;
+    }>;
+    readonly listTags: better_call.StrictEndpoint<"/tags", {
+        method: "GET";
+    }, Tag[]>;
+}, {
+    getAllPosts: (params?: Parameters<typeof getAllPosts>[1]) => Promise<PostListResult>;
+    getPostBySlug: (slug: string) => Promise<(Post & {
+        tags: Tag[];
+    }) | null>;
+    getAllTags: () => Promise<Tag[]>;
+    prefetchForRoute: BlogPrefetchForRoute;
+}>;
+type BlogApiRouter = ReturnType<ReturnType<typeof blogBackendPlugin>["routes"]>;
+
+/**
+ * Internal query key constants for the blog plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+interface PostsListDiscriminator {
+    query: string | undefined;
+    limit: number;
+    published: boolean;
+    tagSlug: string | undefined;
+}
+/** Full query key builders — use these with queryClient.setQueryData() */
+declare const BLOG_QUERY_KEYS: {
+    postsList: (params: {
+        published: boolean;
+        limit?: number;
+        tagSlug?: string;
+    }) => readonly ["posts", "list", PostsListDiscriminator];
+    postDetail: (slug: string) => readonly ["posts", "detail", string];
+    tagsList: () => readonly ["tags", "list", "tags"];
+};
+
+interface PostsListParams {
+    query?: string;
+    limit?: number;
+    published?: boolean;
+    tagSlug?: string;
+}
+declare function createBlogQueryKeys(client: ReturnType<typeof createApiClient<BlogApiRouter>>, headers?: HeadersInit): {
+    posts: {
+        _def: readonly ["posts"];
+    } & {
+        list: ((params?: PostsListParams | undefined) => Omit<Omit<{
+            queryKey: readonly ["posts", "list", PostsListDiscriminator];
+            queryFn: _tanstack_react_query.QueryFunction<unknown, readonly ["posts", "list", PostsListDiscriminator]>;
+        }, "queryFn"> & {
+            _def: readonly ["posts", "list"];
+        }, "_def">) & {
+            _def: readonly ["posts", "list"];
+        };
+        detail: ((slug: string) => Omit<{
+            queryKey: readonly ["posts", "detail", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedPost | null, readonly ["posts", "detail", string]>;
+        } & {
+            _def: readonly ["posts", "detail"];
+        }, "_def">) & {
+            _def: readonly ["posts", "detail"];
+        };
+        nextPrevious: ((date: string | Date) => Omit<{
+            queryKey: readonly ["posts", "nextPrevious", string, string | Date];
+            queryFn: _tanstack_react_query.QueryFunction<{
+                previous: SerializedPost | null;
+                next: SerializedPost | null;
+            }, readonly ["posts", "nextPrevious", string, string | Date]>;
+        } & {
+            _def: readonly ["posts", "nextPrevious"];
+        }, "_def">) & {
+            _def: readonly ["posts", "nextPrevious"];
+        };
+        recent: ((params?: {
+            limit?: number;
+            excludeSlug?: string;
+        } | undefined) => Omit<{
+            queryKey: readonly ["posts", "recent", string, {
+                limit?: number;
+                excludeSlug?: string;
+            } | undefined];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedPost[], readonly ["posts", "recent", string, {
+                limit?: number;
+                excludeSlug?: string;
+            } | undefined]>;
+        } & {
+            _def: readonly ["posts", "recent"];
+        }, "_def">) & {
+            _def: readonly ["posts", "recent"];
+        };
+    };
+    drafts: {
+        _def: readonly ["drafts"];
+    } & {
+        list: ((params?: PostsListParams | undefined) => Omit<Omit<{
+            queryKey: readonly ["drafts", "list", {
+                limit?: number | undefined;
+            }];
+            queryFn: _tanstack_react_query.QueryFunction<unknown, readonly ["drafts", "list", {
+                limit?: number | undefined;
+            }]>;
+        }, "queryFn"> & {
+            _def: readonly ["drafts", "list"];
+        }, "_def">) & {
+            _def: readonly ["drafts", "list"];
+        };
+    };
+    tags: {
+        _def: readonly ["tags"];
+    } & {
+        list: (() => Omit<{
+            queryKey: readonly ["tags", "list", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedTag[], readonly ["tags", "list", string]>;
+        } & {
+            _def: readonly ["tags", "list"];
+        }, "_def">) & {
+            _def: readonly ["tags", "list"];
+        };
+    };
+};
+
+export { BLOG_QUERY_KEYS as B, NextPreviousPostsQuerySchema as N, getPostBySlug as a, getAllTags as b, createBlogQueryKeys as d, PostListQuerySchema as f, getAllPosts as g, blogBackendPlugin as j };
+export type { PostListParams as P, PostListResult as c, BlogRouteKey as e, BlogApiContext as h, BlogBackendHooks as i, BlogApiRouter as k };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -458,7 +458,7 @@
   },
   "peerDependencies": {
     "@ai-sdk/react": ">=2.0.0",
-    "@btst/yar": ">=1.1.0",
+    "@btst/yar": ">=1.2.0",
     "@hookform/resolvers": ">=5.0.0",
     "@radix-ui/react-dialog": ">=1.1.0",
     "@radix-ui/react-label": ">=2.1.0",
@@ -494,7 +494,7 @@
   "devDependencies": {
     "@ai-sdk/react": "^2.0.94",
     "@btst/adapter-memory": "2.0.3",
-    "@btst/yar": "1.1.1",
+    "@btst/yar": "1.2.0",
     "@types/react": "^19.0.0",
     "@types/slug": "^5.0.9",
     "@workspace/ui": "workspace:*",

package/src/plugins/blog/api/index.ts

@@ -6,4 +6,6 @@ export {
 	type PostListParams,
 	type PostListResult,
 } from "./getters";
+export { serializePost, serializeTag } from "./serializers";
+export { BLOG_QUERY_KEYS } from "./query-key-defs";
 export { createBlogQueryKeys } from "../query-keys";

package/src/plugins/blog/api/plugin.ts

@@ -7,6 +7,90 @@ import type { Post, PostWithPostTag, Tag } from "../types";
 import { slugify } from "../utils";
 import { createPostSchema, updatePostSchema } from "../schemas";
 import { getAllPosts, getPostBySlug, getAllTags } from "./getters";
+import { BLOG_QUERY_KEYS } from "./query-key-defs";
+import { serializePost, serializeTag } from "./serializers";
+import type { QueryClient } from "@tanstack/react-query";
+
+/**
+ * Route keys for the blog plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type BlogRouteKey =
+	| "posts"
+	| "drafts"
+	| "post"
+	| "tag"
+	| "newPost"
+	| "editPost";
+
+/**
+ * Overloaded signature for `prefetchForRoute`.
+ * TypeScript enforces the correct params for each routeKey at call sites.
+ */
+interface BlogPrefetchForRoute {
+	(key: "posts" | "drafts" | "newPost", qc: QueryClient): Promise<void>;
+	(
+		key: "post" | "editPost",
+		qc: QueryClient,
+		params: { slug: string },
+	): Promise<void>;
+	(key: "tag", qc: QueryClient, params: { tagSlug: string }): Promise<void>;
+}
+
+function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
+	return async function prefetchForRoute(
+		key: BlogRouteKey,
+		qc: QueryClient,
+		params?: Record<string, string>,
+	): Promise<void> {
+		switch (key) {
+			case "posts":
+			case "drafts": {
+				const published = key === "posts";
+				const [result, tags] = await Promise.all([
+					getAllPosts(adapter, { published, limit: 10 }),
+					getAllTags(adapter),
+				]);
+				qc.setQueryData(BLOG_QUERY_KEYS.postsList({ published, limit: 10 }), {
+					pages: [result.items.map(serializePost)],
+					pageParams: [0],
+				});
+				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				break;
+			}
+			case "post":
+			case "editPost": {
+				const slug = params?.slug ?? "";
+				if (slug) {
+					const post = await getPostBySlug(adapter, slug);
+					qc.setQueryData(
+						BLOG_QUERY_KEYS.postDetail(slug),
+						post ? serializePost(post) : null,
+					);
+				}
+				break;
+			}
+			case "tag": {
+				const tagSlug = params?.tagSlug ?? "";
+				const [result, tags] = await Promise.all([
+					getAllPosts(adapter, { published: true, limit: 10, tagSlug }),
+					getAllTags(adapter),
+				]);
+				qc.setQueryData(
+					BLOG_QUERY_KEYS.postsList({ published: true, limit: 10, tagSlug }),
+					{
+						pages: [result.items.map(serializePost)],
+						pageParams: [0],
+					},
+				);
+				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				break;
+			}
+			default:
+				break;
+		}
+	} as BlogPrefetchForRoute;
+}
 
 export const PostListQuerySchema = z.object({
 	slug: z.string().optional(),
@@ -174,6 +258,7 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 				getAllPosts(adapter, params),
 			getPostBySlug: (slug: string) => getPostBySlug(adapter, slug),
 			getAllTags: () => getAllTags(adapter),
+			prefetchForRoute: createBlogPrefetchForRoute(adapter),
 		}),
 
 		routes: (adapter: Adapter) => {

package/src/plugins/blog/api/query-key-defs.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal query key constants for the blog plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface PostsListDiscriminator {
+	query: string | undefined;
+	limit: number;
+	published: boolean;
+	tagSlug: string | undefined;
+}
+
+/**
+ * Builds the discriminator object used as the cache key for the posts list.
+ * Mirrors the inline object in createPostsQueries so both paths stay in sync.
+ */
+export function postsListDiscriminator(params: {
+	published: boolean;
+	limit?: number;
+	tagSlug?: string;
+	query?: string;
+}): PostsListDiscriminator {
+	return {
+		query:
+			params.query !== undefined && params.query.trim() === ""
+				? undefined
+				: params.query,
+		limit: params.limit ?? 10,
+		published: params.published,
+		tagSlug: params.tagSlug,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const BLOG_QUERY_KEYS = {
+	postsList: (params: {
+		published: boolean;
+		limit?: number;
+		tagSlug?: string;
+	}) => ["posts", "list", postsListDiscriminator(params)] as const,
+
+	postDetail: (slug: string) => ["posts", "detail", slug] as const,
+
+	tagsList: () => ["tags", "list", "tags"] as const,
+};

package/src/plugins/blog/api/serializers.ts

@@ -0,0 +1,27 @@
+import type { Post, Tag, SerializedPost, SerializedTag } from "../types";
+
+/**
+ * Serialize a Tag for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeTag(tag: Tag): SerializedTag {
+	return {
+		...tag,
+		createdAt: tag.createdAt.toISOString(),
+		updatedAt: tag.updatedAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a Post (with tags) for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializePost(post: Post & { tags: Tag[] }): SerializedPost {
+	return {
+		...post,
+		createdAt: post.createdAt.toISOString(),
+		updatedAt: post.updatedAt.toISOString(),
+		publishedAt: post.publishedAt?.toISOString(),
+		tags: post.tags.map(serializeTag),
+	};
+}

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

@@ -1,6 +1,7 @@
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -226,6 +227,12 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -299,6 +306,12 @@ function createPostLoader(
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -398,6 +411,12 @@ function createTagLoader(tagSlug: string, config: BlogClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}