spacetimedb-best-practices

SpacetimeDB のベストプラクティス

TypeScript サーバーモジュールと React とのクライアント SDK 統合の両方を対象とした、SpacetimeDB アプリケーションの包括的な開発ガイドです。自動リファクタリングとコード生成の指針として、影響度順に優先順位付けされた 8 つのカテゴリのルールを掲載しています。

パッケージ： spacetimedb（v1.4.0+）

適用するタイミング

以下の場合に、このガイドラインを参照してください。

• TypeScript で SpacetimeDB サーバーモジュールを記述する
• テーブルスキーマとインデックスを設計する
• 状態変更用の Reducer を実装する
• クライアントのサブスクリプションとクエリを設定する
• SpacetimeDB を React アプリケーションに統合する
• リアルタイム同期のパフォーマンスを最適化する

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	モジュール設計	CRITICAL	module-
2	テーブルスキーマとインデックス作成	CRITICAL	table-
3	Reducer パターン	HIGH	reducer-
4	サブスクリプションの最適化	HIGH	subscription-
5	クライアントの状態管理	MEDIUM-HIGH	client-
6	React 統合	MEDIUM	react-
7	TypeScript パターン	MEDIUM	ts-
8	リアルタイム同期	LOW-MEDIUM	sync-

クイックリファレンス

サーバーモジュール 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 */ });

クライアント 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 統合

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>);
}

ルールカテゴリ

1. モジュール設計（CRITICAL）

• module-single-responsibility - ドメイン概念ごとにモジュールを 1 つにする
• module-lifecycle - ライフサイクルフック（init、clientConnected、clientDisconnected）を適切に使用する
• module-error-handling - モジュールのコードでエラーを適切に処理する
• module-type-exports - クライアントで使用する型をエクスポートする

2. テーブルスキーマとインデックス作成（CRITICAL）

• table-primary-keys - 適切な主キー戦略を選択する
• table-indexing - 頻繁にクエリされる列に .index() を追加する
• table-relationships - テーブル間のリレーションシップを正しくモデル化する
• table-column-types - 適切な SpacetimeDB 型を使用する

3. Reducer パターン（HIGH）

• reducer-atomicity - Reducer をアトミックに保ち、処理を明確にする
• reducer-validation - Reducer の開始時に入力を検証する
• reducer-authorization - 機密性の高い操作では呼び出し元の ID を確認する
• reducer-batch-operations - 関連する変更を 1 つの Reducer でまとめて処理する

4. サブスクリプションの最適化（HIGH）

• subscription-selective - 必要なデータのみをサブスクライブする
• subscription-filters - サブスクリプションフィルターを使用してデータ転送量を減らす
• subscription-cleanup - 不要になったサブスクリプションをクリーンアップする
• subscription-batching - クライアント接続時にサブスクリプションの設定をまとめて行う

5. クライアントの状態管理（MEDIUM-HIGH）

• client-connection-lifecycle - 接続と再接続を適切に処理する
• client-optimistic-updates - UI の応答性を高めるために楽観的更新を使用する
• client-error-recovery - Reducer のエラーを適切に処理する
• client-identity - ID トークンを安全に管理する

6. React 統合（MEDIUM）

• react-use-subscription - サブスクリプションフックを正しく使用する
• react-table-hooks - リアクティブデータには useTable<DbConnection, Type>() を使用する
• react-reducer-hooks - 適切なエラー処理とともに conn.reducers.* を呼び出す
• react-connection-status - 接続状態をユーザーに表示する

7. TypeScript パターン（MEDIUM）

• ts-generated-types - SpacetimeDB CLI で生成された型を使用する
• ts-strict-mode - 型安全性を高めるために TypeScript の strict モードを有効にする
• ts-discriminated-unions - 状態の表現に判別可能なユニオンを使用する
• ts-type-guards - 実行時検証のために型ガードを実装する

8. リアルタイム同期（LOW-MEDIUM）

• sync-conflict-resolution - 同時変更を処理する
• sync-offline-support - 必要に応じてオフラインファーストを前提に設計する
• sync-debounce-updates - UI の頻繁な更新をデバウンスする
• sync-presence - ユーザーのプレゼンスを効率的に実装する

使用方法

詳しい説明とコード例については、各ルールファイルをお読みください。

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

各ルールファイルには、次の内容が含まれています。

• 重要な理由の簡潔な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料

完全版ドキュメント

すべてのルールを詳しく記載したガイドについては、AGENTS.md をご覧ください。