Implements React Hooks for the TypeScript SDK

crates/bindings-typescript/package.json

@@ -54,6 +54,12 @@
       "require": "./dist/sdk/index.cjs",
       "default": "./dist/sdk/index.mjs"
     },
+    "./react": {
+      "types": "./src/react/index.ts",
+      "import": "./dist/react/index.mjs",
+      "require": "./dist/react/index.cjs",
+      "default": "./dist/react/index.mjs"
+    },
     "./server": {
       "types": "./src/server/index.ts",
       "import": "./dist/server/index.mjs",
@@ -104,6 +110,23 @@
       "brotli": false,
       "limit": "60 kB"
     },
+    {
+      "name": "react esm min (brotli)",
+      "path": "dist/min/react/index.mjs",
+      "brotli": true,
+      "limit": "10 kB"
+    },
+    {
+      "name": "react esm min (uncompressed)",
+      "path": "dist/min/react/index.mjs",
+      "limit": "10 kB"
+    },
+    {
+      "name": "react esm min (gzip)",
+      "path": "dist/min/react/index.mjs",
+      "gzip": true,
+      "limit": "15 kB"
+    },
     {
       "name": "sdk esm min (brotli)",
       "path": "dist/min/sdk/index.browser.mjs",
@@ -127,16 +150,21 @@
     "prettier": "^3.3.3"
   },
   "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0",
     "undici": "^6.19.2"
   },
   "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
     "undici": {
       "optional": true
     }
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@size-limit/file": "^11.2.0",
+    "@types/react": "^19.1.13",
     "@typescript-eslint/eslint-plugin": "^8.18.2",
     "@typescript-eslint/parser": "^8.18.2",
     "@vitest/coverage-v8": "^3.2.4",

crates/bindings-typescript/src/lib/identity.ts

@@ -55,4 +55,11 @@ export class Identity {
   static fromString(str: string): Identity {
     return new Identity(str);
   }
+
+  /**
+   * Zero identity (0x0000000000000000000000000000000000000000000000000000000000000000)
+   */
+  static zero(): Identity {
+    return new Identity(0n);
+  }
 }

crates/bindings-typescript/src/react/SpacetimeDBProvider.ts

@@ -0,0 +1,35 @@
+import { DbConnectionBuilder, type DbConnectionImpl } from '../index';
+import * as React from 'react';
+import { SpacetimeDBContext } from './useSpacetimeDB';
+
+export interface SpacetimeDBProviderProps<
+  DbConnection extends DbConnectionImpl,
+  ErrorContext,
+  SubscriptionEventContext,
+> {
+  connectionBuilder: DbConnectionBuilder<
+    DbConnection,
+    ErrorContext,
+    SubscriptionEventContext
+  >;
+  children?: React.ReactNode;
+}
+
+export function SpacetimeDBProvider<
+  DbConnection extends DbConnectionImpl,
+  ErrorContext,
+  SubscriptionEventContext,
+>({
+  connectionBuilder,
+  children,
+}: SpacetimeDBProviderProps<
+  DbConnection,
+  ErrorContext,
+  SubscriptionEventContext
+>): React.JSX.Element {
+  return React.createElement(
+    SpacetimeDBContext.Provider,
+    { value: connectionBuilder.build() }, // May need to modify this to do it lazily in server-side rendering
+    children
+  );
+}

crates/bindings-typescript/src/react/index.ts

@@ -0,0 +1,3 @@
+export * from './SpacetimeDBProvider.ts';
+export { useSpacetimeDB } from './useSpacetimeDB.ts';
+export { useTable, where, eq } from './useTable.ts';

crates/bindings-typescript/src/react/useSpacetimeDB.ts

@@ -0,0 +1,19 @@
+import { createContext, useContext, type Context } from 'react';
+import type { DbConnectionImpl } from '../index';
+
+export const SpacetimeDBContext: Context<DbConnectionImpl | undefined> =
+  createContext<DbConnectionImpl | undefined>(undefined);
+
+// Throws an error if used outside of a SpacetimeDBProvider
+// Error is caught by other hooks like useTable so they can provide better error messages
+export function useSpacetimeDB<
+  DbConnection extends DbConnectionImpl,
+>(): DbConnection {
+  const context = useContext(SpacetimeDBContext) as DbConnection | undefined;
+  if (!context) {
+    throw new Error(
+      'useSpacetimeDB must be used within a SpacetimeDBProvider component. Did you forget to add a `SpacetimeDBProvider` to your component tree?'
+    );
+  }
+  return context;
+}