@multiplatform.one/frappe-ui 7.7.4 → 7.8.0

package/src/FrappeForm.tsx

@@ -171,11 +171,15 @@ export interface AssignmentTodoRow {
   reference_name?: string;
 }
 
-/** Resolves a Frappe file field value (e.g. `/files/x.png`) to a full URL. */
-export function resolveFileUrl(value: unknown, baseURL: string): string | undefined {
+/**
+ * Resolves a Frappe file field value (e.g. `/files/x.png`) to a full URL.
+ * A site-relative path needs a server to hang off, so it resolves to nothing
+ * on a fixtures-only host (no baseURL); absolute URLs still pass through.
+ */
+export function resolveFileUrl(value: unknown, baseURL: string | undefined): string | undefined {
   if (!value || typeof value !== "string") return undefined;
   if (value.startsWith("http://") || value.startsWith("https://")) return value;
-  if (value.startsWith("/")) return `${baseURL.replace(/\/$/, "")}${value}`;
+  if (value.startsWith("/")) return baseURL ? `${baseURL.replace(/\/$/, "")}${value}` : undefined;
   return value;
 }
 
@@ -326,6 +330,7 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
       socketBaseURL: config?.socketBaseURL,
       auth: finalAuth,
       syncOptions: finalSyncOptions,
+      realtime: config?.realtime,
       fixtures: config?.fixtures,
     }),
     [
@@ -333,6 +338,7 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
       config?.socketPort,
       config?.siteName,
       config?.socketBaseURL,
+      config?.realtime,
       finalAuth,
       finalSyncOptions,
       config?.fixtures,

package/src/FrappeGantt.tsx

@@ -1,14 +1,13 @@
-import { useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
 import {
+  Alert,
   GanttView,
   type GanttItemMoveRange,
   type GanttTask,
   type GanttZoom,
 } from "@multiplatform.one/components";
 import React, { useCallback, useMemo, useState, type ReactNode } from "react";
-import { Text, YStack, type YStackProps } from "tamagui";
+import { YStack, type YStackProps } from "tamagui";
 import { useTranslation } from "react-i18next";
-import { formCommonColors } from "@multiplatform.one/forms";
 import {
   formatCalendarDate,
   parseCalendarDate,
@@ -18,6 +17,7 @@ import {
 import { FrappeConnectionIndicator } from "./FrappeConnectionIndicator";
 import { useFrappeConfig } from "./FrappeProvider";
 import { describeSyncError } from "./syncError";
+import { useFrappeRows } from "./useFrappeRows";
 import { resolveFrappeEventColor } from "./frappeEventColor";
 
 export interface FrappeGanttProps<TDoc extends { name: string; doctype: string }> extends Omit<
@@ -113,16 +113,13 @@ export function FrappeGantt<TDoc extends { name: string; doctype: string }>({
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
   const [actionError, setActionError] = useState<Error | null>(null);
-  // Honest error state: the collection swallows failed subscription fetches
-  // (the chart would just look empty) — onSyncError reports them here.
-  const [syncError, setSyncError] = useState<unknown>(null);
 
   const finalBaseURL = baseURL ?? config?.baseURL;
   const finalAuth = auth ?? config?.auth;
   const finalSyncOptions = syncOptions ?? config?.syncOptions;
 
-  if (!finalBaseURL) {
-    throw new Error("FrappeGantt requires baseURL prop or FrappeProvider with baseURL");
+  if (!finalBaseURL && !config?.fixtures) {
+    throw new Error("FrappeGantt requires baseURL prop or FrappeProvider with baseURL or fixtures");
   }
 
   // Ensure required fields are fetched
@@ -146,6 +143,7 @@ export function FrappeGantt<TDoc extends { name: string; doctype: string }>({
       auth: finalAuth,
       syncOptions: finalSyncOptions,
       socketOptions: config?.socketOptions,
+      realtime: config?.realtime,
       fixtures: config?.fixtures,
     }),
     [
@@ -153,6 +151,7 @@ export function FrappeGantt<TDoc extends { name: string; doctype: string }>({
       config?.socketPort,
       config?.siteName,
       config?.socketBaseURL,
+      config?.realtime,
       finalAuth,
       finalSyncOptions,
       config?.socketOptions,
@@ -160,25 +159,29 @@ export function FrappeGantt<TDoc extends { name: string; doctype: string }>({
     ],
   );
 
-  const collection = useFrappeCollection<TDoc>(connectionConfig, doctype, {
+  // The shared doctype read (MPO-251). `mapError` keeps this chart's own
+  // error copy (describeSyncError); real subscription failures still win over
+  // the generic isError flag inside the hook, because they carry an
+  // actionable message. `limit: null` keeps the bench's own page length.
+  const mapSyncError = useCallback(
+    (err: unknown) => new Error(describeSyncError(err, doctype, t)),
+    [doctype, t],
+  );
+  const {
+    rows: docs,
+    isQueryLoading: isLoading,
+    error: queryError,
+    collection,
+  } = useFrappeRows<TDoc>(connectionConfig, doctype, {
     fields: effectiveFields,
     filters,
-    onSyncError: setSyncError,
+    limit: null,
+    mapError: mapSyncError,
+    messages: {
+      permission: t("You do not have permission to view {{doctype}}", { doctype }),
+      generic: t("Failed to load {{doctype}} tasks", { doctype }),
+    },
   });
-  const {
-    data: rawData,
-    isLoading,
-    isError,
-  } = useLiveQuery((q) => (collection ? q.from({ _list: collection }) : null), [collection]);
-  const docs = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
-  // Real subscription failures (permission-error, network, bad doctype) win
-  // over the generic isError flag — they carry an actionable message.
-  const queryError =
-    syncError !== null && syncError !== undefined
-      ? new Error(describeSyncError(syncError, doctype, t))
-      : isError
-        ? new Error(t("Failed to load {{doctype}} tasks", { doctype }))
-        : null;
 
   // Scheme-aware palette for resolving NAMED doc colors (P-15 / LC-27):
   // Frappe's palette references ("blue", "Red") map to sanctioned solids per
@@ -253,23 +256,12 @@ export function FrappeGantt<TDoc extends { name: string; doctype: string }>({
     <YStack {...knobProps.gap}>
       <FrappeConnectionIndicator config={connectionConfig} />
       {actionError ? (
-        <YStack
-          {...knobProps.panelPadding}
-          {...knobProps.borderRadius}
-          backgroundColor="$red2"
-          borderColor="$red7"
-          borderWidth={1}
-        >
-          <Text color={formCommonColors.error} {...knobProps.label}>
-            {t("Action failed")}
-          </Text>
-          <Text color={formCommonColors.muted} {...knobProps.label}>
-            {actionError.message}
-          </Text>
-        </YStack>
+        <Alert intent="error" title={t("Action failed")}>
+          {actionError.message}
+        </Alert>
       ) : null}
       <GanttView
-        {...knobProps.borderRadius}
+        {...knobProps.containerRadius}
         tasks={tasks}
         zoom={zoom}
         isLoading={isLoading}

package/src/FrappeImageView.tsx

@@ -4,7 +4,7 @@ import { ImageSquareIcon } from "@phosphor-icons/react";
 import React, { useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { Spinner, formCommonColors } from "@multiplatform.one/forms";
-import { Image, Text, YStack, type YStackProps } from "tamagui";
+import { Image, Text, YStack, useTheme, type YStackProps } from "tamagui";
 import { isServer } from "@multiplatform.one/platform";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { useFrappeConfig } from "./FrappeProvider";
@@ -167,6 +167,7 @@ function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
   syncOptions,
   ...stackProps
 }: FrappeImageViewProps<TDoc>) {
+  const theme = useTheme();
   const config = useFrappeConfig();
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
@@ -190,6 +191,7 @@ function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
       socketBaseURL: config?.socketBaseURL,
       auth: finalAuth,
       syncOptions: finalSyncOptions,
+      realtime: config?.realtime,
       fixtures: config?.fixtures,
     }),
     [
@@ -197,6 +199,7 @@ function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
       config?.socketPort,
       config?.siteName,
       config?.socketBaseURL,
+      config?.realtime,
       finalAuth,
       finalSyncOptions,
       config?.fixtures,
@@ -271,7 +274,7 @@ function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
     const iconSize = Number(knobProps.controlIcon?.width) || 16;
     return (
       <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap} {...stackProps}>
-        <ImageSquareIcon size={iconSize * 2} color={formCommonColors.muted} />
+        <ImageSquareIcon size={iconSize * 2} color={theme.color11?.val ?? "currentColor"} />
         <Text color={formCommonColors.muted} {...knobProps.body}>
           {t("No image field configured for {{doctype}}", { doctype })}
         </Text>
@@ -330,6 +333,7 @@ function FrappeImageCard({
   onItemClick?: (doc: Partial<unknown>) => void;
   knobProps: ReturnType<typeof useResolvedKnobs>["knobProps"];
 }) {
+  const theme = useTheme();
   const imageUrl = getImageUrl(doc[imageField], baseURL);
   const title = doc[titleField] || doc.name;
   const subtitle = subtitleField ? doc[subtitleField] : undefined;
@@ -369,7 +373,7 @@ function FrappeImageCard({
           alignItems="center"
           justifyContent="center"
         >
-          <ImageSquareIcon size={iconSize * 2} color={formCommonColors.muted} />
+          <ImageSquareIcon size={iconSize * 2} color={theme.color11?.val ?? "currentColor"} />
         </YStack>
       )}
       <Card.Footer>

package/src/FrappeKPICard.spec.tsx

@@ -0,0 +1,128 @@
+/**
+ * MPO-237: a `dataSource` with no `baseURL` in scope is a misconfiguration,
+ * not static mode. The card asked for a computed figure and there is nowhere
+ * to compute it, so `config.value` must never be painted as the KPI: a wrong
+ * number presented confidently is worse than a visible gap, because nothing
+ * downstream can tell it was never computed.
+ *
+ * Static mode (no `dataSource` at all) is the documented, intended path and
+ * is asserted here too, so the fix cannot over-correct into it.
+ */
+
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { FrappeKPICard } from "./FrappeKPICard";
+import { FrappeProvider } from "./FrappeProvider";
+import { __resetFrappeDevWarnSeen } from "./shared/devWarn";
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+beforeEach(() => {
+  __resetFrappeDevWarnSeen();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const config = { id: "open-todos", title: "Open ToDos", value: 999, format: "number" as const };
+
+describe("FrappeKPICard with a dataSource and no baseURL (MPO-237)", () => {
+  it("does not render config.value as though it were the computed figure", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(<FrappeKPICard config={config} dataSource={{ doctype: "ToDo" }} />);
+
+    expect(screen.queryByText("999")).toBeNull();
+    expect(screen.getByText("Open ToDos is not configured")).toBeInTheDocument();
+    expect(screen.getByText(/no Frappe baseURL is in scope/)).toBeInTheDocument();
+  });
+
+  it("logs a development warning naming the missing baseURL", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(<FrappeKPICard config={config} dataSource={{ doctype: "ToDo" }} />);
+
+    const line = warn.mock.calls.map((call) => String(call[0])).join("\n");
+    expect(line).toContain("[frappe-ui] kpi-datasource-without-baseurl");
+    expect(line).toContain("baseURL");
+    expect(line).toContain("component=FrappeKPICard");
+    expect(line).toContain("id=open-todos");
+    expect(line).toContain("doctype=ToDo");
+  });
+
+  it("warns once per card, not once per render", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { rerender } = renderWithProviders(
+      <FrappeKPICard config={config} dataSource={{ doctype: "ToDo" }} />,
+    );
+    rerender(<FrappeKPICard config={{ ...config }} dataSource={{ doctype: "ToDo" }} />);
+    rerender(<FrappeKPICard config={{ ...config }} dataSource={{ doctype: "ToDo" }} />);
+
+    const lines = warn.mock.calls.filter((call) =>
+      String(call[0]).includes("kpi-datasource-without-baseurl"),
+    );
+    expect(lines).toHaveLength(1);
+  });
+
+  it("stays silent in production", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const previous = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    try {
+      renderWithProviders(<FrappeKPICard config={config} dataSource={{ doctype: "ToDo" }} />);
+    } finally {
+      process.env.NODE_ENV = previous;
+    }
+
+    expect(
+      warn.mock.calls.filter((call) => String(call[0]).includes("kpi-datasource-without-baseurl")),
+    ).toHaveLength(0);
+  });
+});
+
+describe("FrappeKPICard configured paths stay untouched (MPO-237)", () => {
+  it("renders config.value with no warning when no dataSource is set", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(<FrappeKPICard config={config} />);
+
+    expect(screen.getByText("999")).toBeInTheDocument();
+    expect(
+      warn.mock.calls.filter((call) => String(call[0]).includes("kpi-datasource-without-baseurl")),
+    ).toHaveLength(0);
+  });
+
+  it("computes the figure, and does not warn, when the provider supplies a baseURL", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(
+      <FrappeProvider
+        baseURL="http://test"
+        fixtures={
+          new InMemoryFixtureProvider({
+            ToDo: [
+              { name: "TD-1", doctype: "ToDo", status: "Open" },
+              { name: "TD-2", doctype: "ToDo", status: "Open" },
+            ],
+          })
+        }
+      >
+        <FrappeKPICard config={config} dataSource={{ doctype: "ToDo" }} />
+      </FrappeProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByText("2")).toBeInTheDocument());
+    expect(screen.queryByText("999")).toBeNull();
+    expect(
+      warn.mock.calls.filter((call) => String(call[0]).includes("kpi-datasource-without-baseurl")),
+    ).toHaveLength(0);
+  });
+});

package/src/FrappeKPICard.tsx

@@ -11,6 +11,12 @@
  * (permission failures called out explicitly), a subtle stale affordance
  * (the card dims while a post-event refetch is in flight), and "—" when the
  * aggregate has no result (e.g. avg over an empty set).
+ *
+ * A `dataSource` with no `baseURL` in scope (neither the prop nor a
+ * FrappeProvider) is a misconfiguration, not static mode: the caller asked
+ * for a computed figure and there is nowhere to compute it. The card renders
+ * the not-configured surface and warns in dev. It never falls back to
+ * `config.value`, which would present an uncomputed number as the KPI.
  */
 import {
   AsyncBoundary,
@@ -19,10 +25,11 @@ import {
   Skeleton,
   type KPICardConfig,
 } from "@multiplatform.one/components";
-import React, { useMemo } from "react";
+import React, { useEffect, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { type YStackProps } from "tamagui";
 import { useFrappeConfig } from "./FrappeProvider";
+import { frappeDevWarn } from "./shared/devWarn";
 import {
   useFrappeAggregate,
   type FrappeAggregateConnection,
@@ -44,11 +51,13 @@ export interface FrappeKPIDataSource {
 export interface FrappeKPICardProps extends Omit<YStackProps, "children"> {
   /**
    * KPI chrome (title, format, trend, icon…). In live mode `value` is
-   * overridden by the aggregate; in static mode it renders as-is.
+   * overridden by the aggregate; in static mode it renders as-is. With a
+   * `dataSource` and no `baseURL`, `value` is not rendered at all.
    */
   config: KPICardConfig;
   /** When set, the card's value goes live against this doctype. */
   dataSource?: FrappeKPIDataSource;
+  /** Falls back to the FrappeProvider's. Required whenever `dataSource` is set. */
   baseURL?: string;
   auth?: { useToken?: boolean; token?: string; type?: string };
   syncOptions?: unknown;
@@ -87,10 +96,23 @@ export function FrappeKPICard({
           socketBaseURL: providerConfig?.socketBaseURL,
           auth: auth ?? providerConfig?.auth,
           syncOptions: syncOptions ?? providerConfig?.syncOptions,
+          realtime: providerConfig?.realtime,
           fixtures: providerConfig?.fixtures,
         }
       : undefined;
 
+  const missingBaseURL = !!dataSource && !finalBaseURL;
+  const doctype = dataSource?.doctype;
+  useEffect(() => {
+    if (!missingBaseURL) return;
+    frappeDevWarn("kpi-datasource-without-baseurl", {
+      component: "FrappeKPICard",
+      id: config.id,
+      doctype,
+      suggest: "set baseURL on FrappeKPICard or on the FrappeProvider above it",
+    });
+  }, [missingBaseURL, config.id, doctype]);
+
   const { value, isLoading, isStale, error, isPermissionError } = useFrappeAggregate(connection, {
     doctype: dataSource?.doctype ?? "",
     aggregate: dataSource?.aggregate,
@@ -105,11 +127,30 @@ export function FrappeKPICard({
     return { ...config, value: value ?? "—" };
   }, [config, dataSource, value]);
 
-  // Static passthrough — same component object semantics as before.
-  if (!dataSource || !connection) {
+  // Static passthrough. The caller supplied the figure and asked for no
+  // computation.
+  if (!dataSource) {
     return <KPICard config={config} {...stackProps} />;
   }
 
+  // A requested figure with nowhere to compute it. `config.value` is the
+  // caller's placeholder, so painting it here would publish a number nothing
+  // downstream could tell was never computed.
+  if (!connection) {
+    return (
+      <AsyncBoundary
+        compact
+        error
+        errorTitle={t("{{title}} is not configured", { title: config.title })}
+        errorDescription={t(
+          "This card reads {{doctype}} live, but no Frappe baseURL is in scope, so the figure was never computed.",
+          { doctype: dataSource.doctype },
+        )}
+        {...stackProps}
+      />
+    );
+  }
+
   if (isLoading) {
     return <KPICardSkeleton {...stackProps} />;
   }

package/src/FrappeKanban.tsx

@@ -1,4 +1,3 @@
-import { useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
 import {
   Kanban,
   componentColors,
@@ -15,6 +14,7 @@ import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { FrappeConnectionIndicator } from "./FrappeConnectionIndicator";
 import { useFrappeConfig } from "./FrappeProvider";
 import { describeSyncError } from "./syncError";
+import { useFrappeRows } from "./useFrappeRows";
 
 /**
  * Configuration for a single Kanban column.
@@ -91,16 +91,15 @@ export function FrappeKanban<TDoc extends { name: string; doctype: string }>({
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
   const [actionError, setActionError] = useState<Error | null>(null);
-  // Honest error state: the collection swallows failed subscription fetches
-  // (board would just look empty) — onSyncError reports them here.
-  const [syncError, setSyncError] = useState<unknown>(null);
 
   const finalBaseURL = baseURL ?? config?.baseURL;
   const finalAuth = auth ?? config?.auth;
   const finalSyncOptions = syncOptions ?? config?.syncOptions;
 
-  if (!finalBaseURL) {
-    throw new Error("FrappeKanban requires baseURL prop or FrappeProvider with baseURL");
+  if (!finalBaseURL && !config?.fixtures) {
+    throw new Error(
+      "FrappeKanban requires baseURL prop or FrappeProvider with baseURL or fixtures",
+    );
   }
 
   // Ensure required fields are fetched
@@ -123,6 +122,7 @@ export function FrappeKanban<TDoc extends { name: string; doctype: string }>({
       auth: finalAuth,
       syncOptions: finalSyncOptions,
       socketOptions: config?.socketOptions,
+      realtime: config?.realtime,
       fixtures: config?.fixtures,
     }),
     [
@@ -130,6 +130,7 @@ export function FrappeKanban<TDoc extends { name: string; doctype: string }>({
       config?.socketPort,
       config?.siteName,
       config?.socketBaseURL,
+      config?.realtime,
       finalAuth,
       finalSyncOptions,
       config?.socketOptions,
@@ -137,17 +138,25 @@ export function FrappeKanban<TDoc extends { name: string; doctype: string }>({
     ],
   );
 
-  const collection = useFrappeCollection<TDoc>(connectionConfig, doctype, {
+  // The shared doctype read (MPO-251). `mapError` keeps this board's own
+  // error copy (describeSyncError) rather than the hook's default shape, and
+  // `limit: null` keeps the bench's own page length.
+  const mapSyncError = useCallback(
+    (err: unknown) => new Error(describeSyncError(err, doctype, t)),
+    [doctype, t],
+  );
+  const {
+    rows: cards,
+    isQueryLoading: isLoading,
+    isError,
+    syncError,
+    collection,
+  } = useFrappeRows<TDoc>(connectionConfig, doctype, {
     fields: effectiveFields,
     filters,
-    onSyncError: setSyncError,
+    limit: null,
+    mapError: mapSyncError,
   });
-  const {
-    data: rawData,
-    isLoading,
-    isError,
-  } = useLiveQuery((q) => (collection ? q.from({ _list: collection }) : null), [collection]);
-  const cards = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
 
   // Group cards by status into generic KanbanColumn format.
   // Cards with an unknown status land in an "Unassigned" column so they
@@ -284,9 +293,9 @@ export function FrappeKanban<TDoc extends { name: string; doctype: string }>({
   // Real subscription failure (permission-error, network, bad doctype)
   // reported by the collection via onSyncError — honest error UI instead of
   // an empty board. The `error` render prop stays the consumer override.
-  const boardError = syncError != null ? describeSyncError(syncError, doctype, t) : null;
-  if (boardError && error) {
-    return <>{error(new Error(boardError))}</>;
+  const boardError = syncError ? syncError.message : null;
+  if (syncError && error) {
+    return <>{error(syncError)}</>;
   }
 
   // Opt-in query error panel via `error` prop. Empty/fixture-less collections

package/src/FrappeLikedBy.tsx

@@ -131,6 +131,7 @@ function FrappeLikedByBody({
             socketBaseURL: config.socketBaseURL,
             auth: config.auth,
             syncOptions: config.syncOptions,
+            realtime: config.realtime,
             fixtures: config.fixtures,
           }
         : undefined,
@@ -167,7 +168,7 @@ function FrappeLikedByBody({
 
   const http = useMemo(
     () =>
-      config && !config.fixtures
+      config?.baseURL && !config.fixtures
         ? new HttpClient(
             config.baseURL,
             config.auth as Parameters<typeof HttpClient.prototype.updateAuth>[0],

package/src/FrappeList.tsx

@@ -51,8 +51,9 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
   const finalAuth = auth ?? config?.auth;
   const finalSyncOptions = syncOptions ?? config?.syncOptions;
 
-  if (!finalBaseURL) {
-    throw new Error("FrappeList requires baseURL prop or FrappeProvider with baseURL");
+  // Fixtures answer every read locally, so they stand in for a baseURL.
+  if (!finalBaseURL && !config?.fixtures) {
+    throw new Error("FrappeList requires baseURL prop or FrappeProvider with baseURL or fixtures");
   }
 
   const connectionConfig = useMemo(
@@ -63,6 +64,7 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
       socketBaseURL: config?.socketBaseURL,
       auth: finalAuth,
       syncOptions: finalSyncOptions,
+      realtime: config?.realtime,
       fixtures: config?.fixtures,
     }),
     [
@@ -70,6 +72,7 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
       config?.socketPort,
       config?.siteName,
       config?.socketBaseURL,
+      config?.realtime,
       finalAuth,
       finalSyncOptions,
       config?.fixtures,

package/src/FrappeListView.tsx

@@ -149,6 +149,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
     socketBaseURL: config?.socketBaseURL,
     auth: finalAuth,
     syncOptions: finalSyncOptions,
+    realtime: config?.realtime,
     fixtures: config?.fixtures,
   };