Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Before diving into the reference, you may want to review:
| [React Integration](#react-integration) | React hooks and components for SpacetimeDB (`spacetimedb/react`). |
| [Identify a client](#identify-a-client) | Types for identifying users and client connections. |
| [Query Builder API](#query-builder-api) | Type-safe query builder for subscriptions using the `tables` export. |
| [Framework Integrations](#framework-integrations) | React, Vue, and Svelte hooks for reactive SpacetimeDB data. |
| [Framework Integrations](#framework-integrations) | React, SolidJS, Vue, and Svelte hooks for reactive SpacetimeDB data. |

## Project setup

Expand Down Expand Up @@ -1025,6 +1025,7 @@ The React integration is fully compatible with React StrictMode and correctly ha
| [`SpacetimeDBProvider` component](#component-spacetimedbprovider) | Context provider that manages the database connection. |
| [`useSpacetimeDB` hook](#hook-usespacetimedb) | Access the connection and connection state. |
| [`useTable` hook](#hook-usetable) | Subscribe to table data with automatic re-renders. |
| [`useReducer` hook](#hook-usereducer) | Call reducers from components. |

### Component `SpacetimeDBProvider`

Expand All @@ -1035,15 +1036,15 @@ import { SpacetimeDBProvider } from 'spacetimedb/react';
Wrap your application with `SpacetimeDBProvider` to provide connection context to child components. Pass a configured `DbConnectionBuilder` (without calling `.build()`).

```tsx
import { DbConnection } from './module_bindings';
import { DbConnection, tables } from './module_bindings';
import { SpacetimeDBProvider } from 'spacetimedb/react';

const connectionBuilder = DbConnection.builder()
.withUri('ws://localhost:3000')
.withDatabaseName('my-module')
.onConnect((conn, identity, token) => {
console.log('Connected:', identity.toHexString());
conn.subscriptionBuilder().subscribe('SELECT * FROM player');
conn.subscriptionBuilder().subscribe(tables.player);
})
.onDisconnect(() => console.log('Disconnected'));

Expand Down Expand Up @@ -1098,21 +1099,21 @@ function MyComponent() {
```tsx
import { useTable } from 'spacetimedb/react';

function useTable<DbConnection, Row>(tableName: string): {
rows: Row[];
loading: boolean;
};
function useTable<TableDef extends UntypedTableDef>(
query: Query<TableDef>,
callbacks?: UseTableCallbacks<RowType<TableDef>>
): [readonly RowType<TableDef>[], boolean];
```

Subscribe to a table and receive automatic re-renders when rows change. Returns the current rows and a loading state.
Subscribe to a table or filtered query and receive automatic re-renders when rows change. Returns a tuple of `[rows, isReady]`.

```tsx
import { Player } from './module_bindings';
import { tables } from './module_bindings';

function PlayerList() {
const { rows: players, loading } = useTable<DbConnection, Player>('player');
const [players, isReady] = useTable(tables.player);

if (loading) {
if (!isReady) {
return <div>Loading players...</div>;
}

Expand All @@ -1126,6 +1127,18 @@ function PlayerList() {
}
```

### Hook `useReducer`

```tsx
import { useReducer } from 'spacetimedb/react';
import { reducers } from './module_bindings';

const createPlayer = useReducer(reducers.createPlayer);
createPlayer('Alice');
```

`useReducer` returns a function that calls the generated reducer. Calls made before the connection is ready are queued and flushed once the connection is established.

## Identify a client

### Type `Identity`
Expand All @@ -1146,7 +1159,7 @@ An opaque identifier for a client connection to a database, intended to differen

## Framework Integrations

The SpacetimeDB TypeScript SDK includes built-in integrations for React, Vue, and Svelte. These provide reactive hooks that automatically subscribe to queries and re-render when data changes.
The SpacetimeDB TypeScript SDK includes built-in integrations for React, SolidJS, Vue, and Svelte. These provide reactive hooks that automatically subscribe to queries and re-render when data changes.

### React

Expand Down Expand Up @@ -1229,9 +1242,46 @@ const sendMessage = useReducer(reducers.sendMessage);
sendMessage({ text: 'Hello!' });
```

### SolidJS

```typescript
import { SpacetimeDBProvider, useSpacetimeDB, useTable, useReducer, useProcedure } from 'spacetimedb/solid';
```

The SolidJS integration provides primitives that use Solid's fine-grained reactivity. `useTable` takes a getter function so queries can depend on signals, and returns `[readonly Row[], () => boolean]`:

```tsx
import { For, Show, createSignal } from 'solid-js';
import { useTable, useReducer } from 'spacetimedb/solid';
import { reducers, tables } from './module_bindings';

const [onlineOnly, setOnlineOnly] = createSignal(false);

const [users, isReady] = useTable(
() => onlineOnly()
? tables.user.where(r => r.online.eq(true))
: tables.user,
{
onInsert: user => console.log('User connected:', user.name),
onDelete: user => console.log('User disconnected:', user.name),
enabled: () => true,
}
);

const sendMessage = useReducer(reducers.sendMessage);

<Show when={isReady()} fallback={<div>Loading users...</div>}>
<button onClick={() => sendMessage('Hello!')}>Send</button>
<button onClick={() => setOnlineOnly(value => !value)}>Toggle online</button>
<For each={users}>{user => <div>{user.name}</div>}</For>
</Show>
```

`useReducer` and `useProcedure` queue calls made before the connection is ready and flush them once connected.

### Vue

```bash
```typescript
import { SpacetimeDBProvider, useSpacetimeDB, useTable, useReducer } from 'spacetimedb/vue';
```

Expand Down Expand Up @@ -1259,7 +1309,7 @@ const [onlineUsers] = useTable(

### Svelte

```bash
```typescript
import { SpacetimeDBProvider, useSpacetimeDB, useTable, useReducer } from 'spacetimedb/svelte';
```

Expand Down
Loading