feat: add react sdk

Author: JulienLavocat

packages/sdk/package.json

@@ -39,7 +39,8 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
-    "undici": "^6.19.2"
+    "undici": "^6.19.2",
+    "react": ">=17.0.0"
   },
   "devDependencies": {
     "@clockworklabs/test-app": "file:../test-app",
@@ -49,5 +50,10 @@
   "dependencies": {
     "@zxing/text-encoding": "^0.9.0",
     "base64-js": "^1.5.1"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }

packages/sdk/src/index.ts

@@ -8,3 +8,5 @@ export * from './identity.ts';
 export * from './message_types.ts';
 export * from './timestamp.ts';
 export * from './time_duration.ts';
+
+export * from './react';

packages/sdk/src/react/SpacetimeDBProvider.tsx

@@ -0,0 +1,89 @@
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type FC,
+  type ReactNode,
+} from 'react';
+import { SpacetimeDBContext } from './useSpacetimeDB';
+import type { DbConnectionBuilder } from '@clockworklabs/spacetimedb-sdk';
+
+export type ConnectionStatus =
+  | 'idle'
+  | 'connecting'
+  | 'connected'
+  | 'disconnected'
+  | 'error';
+
+export const SpacetimeDBProvider: FC<{
+  builder: DbConnectionBuilder<any, any, any>;
+  moduleName: string;
+  uri: string;
+  compression?: 'gzip' | 'none';
+  lightMode?: boolean;
+  children?: ReactNode;
+  fallback?: ReactNode;
+}> = ({
+  builder,
+  moduleName,
+  uri,
+  compression,
+  lightMode,
+  children,
+  fallback,
+}) => {
+  const [client, setClient] = useState<any>(null);
+  const [status, setStatus] = useState<ConnectionStatus>('idle');
+  const aliveRef = useRef(true); // Prevent issues with late events after unmount, especially with StrictMode
+
+  const configuredBuilder = useMemo(() => {
+    return builder
+      .withModuleName(moduleName)
+      .withUri(uri)
+      .withCompression(compression ?? 'gzip')
+      .withLightMode(lightMode ?? false);
+  }, [builder, moduleName, uri, compression, lightMode]);
+
+  useEffect(() => {
+    aliveRef.current = true;
+    setStatus('connecting');
+
+    const b = configuredBuilder
+      .onConnect(() => {
+        if (!aliveRef.current) return;
+        setStatus('connected');
+      })
+      .onDisconnect(() => {
+        if (!aliveRef.current) return;
+        setStatus('disconnected');
+      })
+      .onConnectError(() => {
+        if (!aliveRef.current) return;
+        setStatus('error');
+      });
+
+    const newClient = b.build();
+    setClient((prev: any) => {
+      prev?.disconnect?.();
+      return newClient;
+    });
+
+    return () => {
+      aliveRef.current = false;
+      newClient?.disconnect?.();
+    };
+  }, [configuredBuilder]);
+
+  if (!client || status !== 'connected') {
+    return <>{fallback ?? <div>Connecting to SpacetimeDB…</div>}</>;
+  }
+
+  return (
+    <SpacetimeDBContext.Provider
+      value={{ client, status, identity: client.identity, token: client.token }}
+    >
+      {children}
+    </SpacetimeDBContext.Provider>
+  );
+};

packages/sdk/src/react/index.ts

@@ -0,0 +1,4 @@
+export * from './SpacetimeDBProvider.tsx';
+export { useSpacetimeDB } from './useSpacetimeDB.ts';
+export { useSubscription } from './useSubscription.ts';
+export { useTable } from './useTable.ts';

packages/sdk/src/react/useSpacetimeDB.ts

@@ -0,0 +1,9 @@
+import { createContext, useContext } from "react";
+import type { ConnectionStatus } from "./SpacetimeDBProvider";
+import type { Identity } from "@clockworklabs/spacetimedb-sdk";
+
+export const SpacetimeDBContext = createContext<any>(null);
+
+export function useSpacetimeDB<T>(): { status: ConnectionStatus; client: T; identity: Identity; token: string } {
+  return useContext(SpacetimeDBContext);
+}

packages/sdk/src/react/useSubscription.ts

@@ -0,0 +1,42 @@
+import { useEffect, useMemo, useRef, useCallback } from "react";
+import type { DbConnection } from "../module_bindings";
+import { useSpacetimeDB } from "./useSpacetimeDB";
+
+type UseSubscriptionCallbacks = {
+  onApplied?: () => void;
+  onError?: (error: Error) => void;
+  onUnsubscribed?: () => void;
+};
+
+export function useSubscription(query: string, callbacks?: UseSubscriptionCallbacks) {
+  const { client } = useSpacetimeDB<DbConnection>();
+
+  const cbRef = useRef<UseSubscriptionCallbacks | undefined>(callbacks);
+  cbRef.current = callbacks;
+
+  const cancelRef = useRef<(() => Promise<void> | void) | null>(null);
+
+  const cancel = useCallback(() => {
+    return cancelRef.current?.();
+  }, []);
+
+  useEffect(() => {
+    const subscription = client
+      .subscriptionBuilder()
+      .onApplied(() => cbRef.current?.onApplied?.())
+      .onError((e) => cbRef.current?.onError?.(e as any))
+      .subscribe(query);
+
+    cancelRef.current = () => {
+      subscription.unsubscribe();
+    };
+
+    return () => {
+      const fn = cancelRef.current;
+      cancelRef.current = null;
+      fn?.();
+    };
+  }, [query, client]);
+
+  return useMemo(() => ({ cancel }), [cancel]);
+}

packages/sdk/src/react/useTable.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from "react";
+
+export interface TableCallbacks<TRow> {
+  onInsert?: (row: TRow) => void;
+  onDelete?: (row: TRow) => void;
+  onUpdate?: (oldRow: TRow, newRow: TRow) => void;
+}
+
+export function useTable<TRow>(table: any, callbacks?: TableCallbacks<TRow>): TRow[] {
+  const [rows, setRows] = useState<TRow[]>([]);
+
+  useEffect(() => {
+    table.onInsert((_: any, row: any) => {
+      setRows(table.iter() as TRow[]);
+      if (callbacks?.onInsert) {
+        callbacks.onInsert(row);
+      }
+    });
+
+    table.onDelete((_: any, row: any) => {
+      setRows(table.iter() as TRow[]);
+      if (callbacks?.onDelete) {
+        callbacks.onDelete(row);
+      }
+    });
+
+    if (table.onUpdate) {
+      table.onUpdate((_: any, oldRow: any, newRow: any) => {
+        setRows(table.iter() as TRow[]);
+        if (callbacks?.onUpdate) {
+          callbacks.onUpdate(oldRow, newRow);
+        }
+      });
+    }
+
+    return () => {};
+  }, [table, callbacks]);
+
+  return rows;
+}
+
+// TODO:
+// Add a hook for reducers

packages/sdk/tsconfig.json

@@ -15,7 +15,8 @@
     "moduleResolution": "Bundler",
     "allowSyntheticDefaultImports": true,
     "isolatedDeclarations": true,
-    "isolatedModules": true
+    "isolatedModules": true,
+    "jsx": "react-jsx"
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "**/__tests__/*", "dist/**/*"]