@btst/stack 2.2.0 → 2.3.0

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

@@ -24,6 +24,54 @@ import {
 	updateTaskSchema,
 } from "../schemas";
 import { getAllBoards, getBoardById } from "./getters";
+import { KANBAN_QUERY_KEYS } from "./query-key-defs";
+import { serializeBoard } from "./serializers";
+import type { QueryClient } from "@tanstack/react-query";
+
+/**
+ * Route keys for the Kanban plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type KanbanRouteKey = "boards" | "newBoard" | "board";
+
+interface KanbanPrefetchForRoute {
+	(key: "boards" | "newBoard", qc: QueryClient): Promise<void>;
+	(key: "board", qc: QueryClient, params: { boardId: string }): Promise<void>;
+}
+
+function createKanbanPrefetchForRoute(
+	adapter: Adapter,
+): KanbanPrefetchForRoute {
+	return async function prefetchForRoute(
+		key: KanbanRouteKey,
+		qc: QueryClient,
+		params?: Record<string, string>,
+	): Promise<void> {
+		switch (key) {
+			case "boards": {
+				const result = await getAllBoards(adapter, { limit: 50, offset: 0 });
+				qc.setQueryData(
+					KANBAN_QUERY_KEYS.boardsList({}),
+					result.items.map(serializeBoard),
+				);
+				break;
+			}
+			case "board": {
+				const boardId = params?.boardId ?? "";
+				if (boardId) {
+					const board = await getBoardById(adapter, boardId);
+					qc.setQueryData(
+						KANBAN_QUERY_KEYS.boardDetail(boardId),
+						board ? serializeBoard(board) : null,
+					);
+				}
+				break;
+			}
+			default:
+				break;
+		}
+	} as KanbanPrefetchForRoute;
+}
 
 /**
  * Context passed to kanban API hooks
@@ -268,6 +316,7 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 			getAllBoards: (params?: Parameters<typeof getAllBoards>[1]) =>
 				getAllBoards(adapter, params),
 			getBoardById: (id: string) => getBoardById(adapter, id),
+			prefetchForRoute: createKanbanPrefetchForRoute(adapter),
 		}),
 
 		routes: (adapter: Adapter) => {

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

@@ -0,0 +1,54 @@
+/**
+ * Internal query key constants for the Kanban plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface BoardsListDiscriminator {
+	slug: string | undefined;
+	ownerId: string | undefined;
+	organizationId: string | undefined;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Builds the discriminator object for the boards list query key.
+ * Mirrors the inline object used in createBoardsQueries.list.
+ */
+export function boardsListDiscriminator(params?: {
+	slug?: string;
+	ownerId?: string;
+	organizationId?: string;
+	limit?: number;
+	offset?: number;
+}): BoardsListDiscriminator {
+	return {
+		slug: params?.slug,
+		ownerId: params?.ownerId,
+		organizationId: params?.organizationId,
+		limit: params?.limit ?? 50,
+		offset: params?.offset ?? 0,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const KANBAN_QUERY_KEYS = {
+	/**
+	 * Key for boards.list(params) query.
+	 * Full key: ["boards", "list", { slug, ownerId, organizationId, limit, offset }]
+	 */
+	boardsList: (params?: {
+		slug?: string;
+		ownerId?: string;
+		organizationId?: string;
+		limit?: number;
+		offset?: number;
+	}) => ["boards", "list", boardsListDiscriminator(params)] as const,
+
+	/**
+	 * Key for boards.detail(boardId) query.
+	 * Full key: ["boards", "detail", boardId]
+	 */
+	boardDetail: (boardId: string) => ["boards", "detail", boardId] as const,
+};

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

@@ -0,0 +1,49 @@
+import type {
+	Task,
+	ColumnWithTasks,
+	BoardWithColumns,
+	SerializedTask,
+	SerializedColumn,
+	SerializedBoardWithColumns,
+} from "../types";
+
+/**
+ * Serialize a Task for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeTask(task: Task): SerializedTask {
+	return {
+		...task,
+		completedAt: task.completedAt?.toISOString(),
+		createdAt: task.createdAt.toISOString(),
+		updatedAt: task.updatedAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a Column (with its tasks) for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeColumn(col: ColumnWithTasks): SerializedColumn {
+	return {
+		...col,
+		createdAt: col.createdAt.toISOString(),
+		updatedAt: col.updatedAt.toISOString(),
+		tasks: col.tasks.map(serializeTask),
+	};
+}
+
+/**
+ * Serialize a Board (with columns and tasks) for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeBoard(
+	board: BoardWithColumns,
+): SerializedBoardWithColumns {
+	return {
+		...board,
+		createdAt: board.createdAt.toISOString(),
+		updatedAt: board.updatedAt.toISOString(),
+		columns: board.columns.map(serializeColumn),
+	};
+}

package/src/plugins/kanban/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";
@@ -178,6 +179,12 @@ function createBoardsLoader(config: KanbanClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/kanban] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -241,6 +248,12 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/kanban] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}

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

@@ -5,6 +5,7 @@ import {
 import type { KanbanApiRouter } from "./api";
 import { createApiClient } from "@btst/stack/plugins/client";
 import type { SerializedBoardWithColumns } from "./types";
+import { boardsListDiscriminator } from "./api/query-key-defs";
 
 interface BoardsListParams {
 	slug?: string;
@@ -63,15 +64,7 @@ function createBoardsQueries(
 ) {
 	return createQueryKeys("boards", {
 		list: (params?: BoardsListParams) => ({
-			queryKey: [
-				{
-					slug: params?.slug,
-					ownerId: params?.ownerId,
-					organizationId: params?.organizationId,
-					limit: params?.limit ?? 50,
-					offset: params?.offset ?? 0,
-				},
-			],
+			queryKey: [boardsListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response = await client("/boards", {

package/src/plugins/utils.ts

@@ -1,4 +1,23 @@
 import { createClient } from "better-call/client";
+
+/**
+ * Returns true when a fetch error is a connection-refused / no-server error.
+ * Used in SSR loaders to emit an actionable build-time warning when
+ * `route.loader()` is called during `next build` with no HTTP server running.
+ */
+export function isConnectionError(err: unknown): boolean {
+	if (!(err instanceof Error)) return false;
+	const code =
+		(err as unknown as { cause?: { code?: string } }).cause?.code ??
+		(err as unknown as { code?: string }).code;
+	return (
+		err.message.includes("ECONNREFUSED") ||
+		err.message.includes("fetch failed") ||
+		err.message.includes("ERR_CONNECTION_REFUSED") ||
+		code === "ECONNREFUSED" ||
+		code === "ERR_CONNECTION_REFUSED"
+	);
+}
 import type { Router, Endpoint } from "better-call";
 
 interface CreateApiClientOptions {

package/dist/shared/{stack.BkYlUT_8.d.cts → stack.CBON0dWL.d.cts}

@@ -35,12 +35,6 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
-    title: z.ZodString;
-    slug: z.ZodOptional<z.ZodString>;
-    published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -48,9 +42,15 @@ declare const createPostSchema: z.ZodObject<{
         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>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;

package/dist/shared/{stack.BkYlUT_8.d.mts → stack.CBON0dWL.d.mts}

@@ -35,12 +35,6 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
-    title: z.ZodString;
-    slug: z.ZodOptional<z.ZodString>;
-    published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -48,9 +42,15 @@ declare const createPostSchema: z.ZodObject<{
         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>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;

package/dist/shared/{stack.BkYlUT_8.d.ts → stack.CBON0dWL.d.ts}

@@ -35,12 +35,6 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
-    title: z.ZodString;
-    slug: z.ZodOptional<z.ZodString>;
-    published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -48,9 +42,15 @@ declare const createPostSchema: z.ZodObject<{
         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>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;