SpacetimeDB Best Practices

Comprehensive development guide for SpacetimeDB applications, covering both TypeScript server modules and client SDK integration with React. Contains rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

Package: spacetimedb (v1.4.0+)

When to Apply

Reference these guidelines when:

• •Writing SpacetimeDB server modules in TypeScript
• •Designing table schemas and indexes
• •Implementing reducers for state mutations
• •Setting up client subscriptions and queries
• •Integrating SpacetimeDB with React applications
• •Optimizing real-time sync performance

Rule Categories by Priority

Quick Reference

Server Module API (TypeScript)

import { spacetimedb, table, t, ReducerContext } from 'spacetimedb';

// Define tables with the table builder
const Player = table(
  { name: 'player', public: true },
  {
    identity: t.identity().primaryKey(),
    name: t.string(),
    score: t.u64().index(),
    isOnline: t.bool().index(),
  }
);

// Define reducers
spacetimedb.reducer('create_player', { name: t.string() }, (ctx: ReducerContext, { name }) => {
  ctx.db.player.insert({
    identity: ctx.sender,
    name,
    score: 0n,
    isOnline: true,
  });
});

// Lifecycle hooks
spacetimedb.init((ctx: ReducerContext) => { /* module init */ });
spacetimedb.clientConnected((ctx: ReducerContext) => { /* client connected */ });
spacetimedb.clientDisconnected((ctx: ReducerContext) => { /* client disconnected */ });

Client SDK API (TypeScript)

import { DbConnection } from './generated';

// Build connection
const conn = DbConnection.builder()
  .withUri('ws://localhost:3000')
  .withModuleName('my-module')
  .onConnect((ctx, identity, token) => {
    // Setup subscriptions
    conn.subscription(['SELECT * FROM player WHERE isOnline = true']);
  })
  .onDisconnect((ctx, error) => { /* handle disconnect */ })
  .build();

// Call reducers
await conn.reducers.createPlayer('Alice');

// Access tables
const player = conn.db.player.identity.find(identity);

React Integration

import { useTable, where, eq } from 'spacetimedb/react';
import { DbConnection, Player } from './generated';

function OnlinePlayers() {
  const { rows: players } = useTable<DbConnection, Player>(
    'player',
    where(eq('isOnline', true))
  );

  return players.map(p => <div key={p.identity.toHexString()}>{p.name}</div>);
}

Rule Categories

1. Module Design (CRITICAL)

• •module-single-responsibility - One module per domain concept
• •module-lifecycle - Use lifecycle hooks appropriately (init, clientConnected, clientDisconnected)
• •module-error-handling - Handle errors gracefully in module code
• •module-type-exports - Export types for client consumption

2. Table Schema & Indexing (CRITICAL)

• •table-primary-keys - Choose appropriate primary key strategies
• •table-indexing - Add .index() for frequently queried columns
• •table-relationships - Model relationships between tables correctly
• •table-column-types - Use appropriate SpacetimeDB types

3. Reducer Patterns (HIGH)

• •reducer-atomicity - Keep reducers atomic and focused
• •reducer-validation - Validate inputs at reducer entry
• •reducer-authorization - Check caller identity for sensitive operations
• •reducer-batch-operations - Batch related mutations in single reducer

4. Subscription Optimization (HIGH)

• •subscription-selective - Subscribe only to needed data
• •subscription-filters - Use subscription filters to reduce data transfer
• •subscription-cleanup - Clean up subscriptions when no longer needed
• •subscription-batching - Batch subscription setup on client connect

5. Client State Management (MEDIUM-HIGH)

• •client-connection-lifecycle - Handle connection/reconnection properly
• •client-optimistic-updates - Use optimistic updates for responsive UI
• •client-error-recovery - Handle reducer errors gracefully
• •client-identity - Manage identity tokens securely

6. React Integration (MEDIUM)

• •react-use-subscription - Use subscription hooks correctly
• •react-table-hooks - Use useTable<DbConnection, Type>() for reactive data
• •react-reducer-hooks - Call conn.reducers.* with proper error handling
• •react-connection-status - Display connection status to users

7. TypeScript Patterns (MEDIUM)

• •ts-generated-types - Use generated types from SpacetimeDB CLI
• •ts-strict-mode - Enable strict TypeScript for better type safety
• •ts-discriminated-unions - Use discriminated unions for state
• •ts-type-guards - Implement type guards for runtime validation

8. Real-time Sync (LOW-MEDIUM)

• •sync-conflict-resolution - Handle concurrent modifications
• •sync-offline-support - Design for offline-first when needed
• •sync-debounce-updates - Debounce rapid UI updates
• •sync-presence - Implement user presence efficiently

How to Use

Read individual rule files for detailed explanations and code examples:

rules/module-single-responsibility.md
rules/table-primary-keys.md
rules/_sections.md

Each rule file contains:

• •Brief explanation of why it matters
• •Incorrect code example with explanation
• •Correct code example with explanation
• •Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md