zep/.github/copilot-instructions.md

SpacetimeDB Rules (All Languages)

Migrating from 1.0 to 2.0?

If you are migrating existing SpacetimeDB 1.0 code to 2.0, apply spacetimedb-migration-2.0.mdc first. It documents breaking changes (reducer callbacks → event tables, name→accessor, sender() method, etc.) and should be considered before other rules.

---

Language-Specific Rules

Language	Rule File
TypeScript/React	spacetimedb-typescript.mdc (MANDATORY)
Rust	spacetimedb-rust.mdc (MANDATORY)
C#	spacetimedb-csharp.mdc (MANDATORY)
Migrating 1.0 → 2.0	spacetimedb-migration-2.0.mdc

---

Core Concepts

1. Reducers are transactional — they do not return data to callers
2. Reducers must be deterministic — no filesystem, network, timers, or random
3. Read data via tables/subscriptions — not reducer return values
4. Auto-increment IDs are not sequential — gaps are normal, don't use for ordering
5. ctx.sender is the authenticated principal — never trust identity args

---

Feature Implementation Checklist

When implementing a feature that spans backend and client:

1. Backend: Define table(s) to store the data
2. Backend: Define reducer(s) to mutate the data
3. Client: Subscribe to the table(s)
4. Client: Call the reducer(s) from UI — don't forget this step!
5. Client: Render the data from the table(s)

Common mistake: Building backend tables/reducers but forgetting to wire up the client to call them.

---

Index System

SpacetimeDB automatically creates indexes for:

• Primary key columns
• Columns marked as unique

You can add explicit indexes on non-unique columns for query performance.

Index names must be unique across your entire module (all tables). If two tables have indexes with the same declared name → conflict error.

Schema ↔ Code coupling:

• Your query code references indexes by name
• If you add/remove/rename an index in the schema, update all code that uses it
• Removing an index without updating queries causes runtime errors

---

Commands

# Login to allow remote database deployment e.g. to maincloud
spacetime login

# Start local SpacetimeDB
spacetime start

# Publish module
spacetime publish <db-name> --module-path <module-path>

# Clear and republish
spacetime publish <db-name> --clear-database -y --module-path <module-path>

# Generate client bindings
spacetime generate --lang <lang> --out-dir <out> --module-path <module-path>

# View logs
spacetime logs <db-name>

---

Deployment

• Maincloud is the spacetimedb hosted cloud and the default location for module publishing
• The default server marked by *** in spacetime server list should be used when publishing
• If the default server is maincloud you should publish to maincloud
• Publishing to maincloud is free of charge
• When publishing to maincloud the database dashboard will be at the url: https://spacetimedb.com/@/
• The database owner can view utilization and performance metrics on the dashboard

---

Debugging Checklist

1. Is SpacetimeDB server running? (spacetime start)
2. Is the module published? (spacetime publish)
3. Are client bindings generated? (spacetime generate)
4. Check server logs for errors (spacetime logs <db-name>)
5. Is the reducer actually being called from the client?

---

Editing Behavior

• Make the smallest change necessary
• Do NOT touch unrelated files, configs, or dependencies
• Do NOT invent new SpacetimeDB APIs — use only what exists in docs or this repo
• Do NOT add restrictions the prompt didn't ask for — if "users can do X", implement X for all users

SpacetimeDB TypeScript SDK

⛔ HALLUCINATED APIs — DO NOT USE

These APIs DO NOT EXIST. LLMs frequently hallucinate them.

// ❌ WRONG PACKAGE — does not exist
import { SpacetimeDBClient } from "@clockworklabs/spacetimedb-sdk";

// ❌ WRONG — these methods don't exist
SpacetimeDBClient.connect(...);
SpacetimeDBClient.call("reducer_name", [...]);
connection.call("reducer_name", [arg1, arg2]);

// ❌ WRONG — positional reducer arguments
conn.reducers.doSomething("value");  // WRONG!

// ❌ WRONG — static methods on generated types don't exist
User.filterByName('alice');
Message.findById(123n);
tables.user.filter(u => u.name === 'alice');  // No .filter() on tables object!

✅ CORRECT PATTERNS:

// ✅ CORRECT IMPORTS
import { DbConnection, tables } from "./module_bindings"; // Generated!
import { SpacetimeDBProvider, useTable, Identity } from "spacetimedb/react";

// ✅ CORRECT REDUCER CALLS — object syntax, not positional!
conn.reducers.doSomething({ value: "test" });
conn.reducers.updateItem({ itemId: 1n, newValue: 42 });

// ✅ CORRECT DATA ACCESS — useTable returns [rows, isLoading]
const [items, isLoading] = useTable(tables.item);

⛔ DO NOT:

• Invent hooks like useItems(), useData() — use useTable(tables.tableName)
• Import from fake packages — only spacetimedb, spacetimedb/react, ./module_bindings

---

1) Common Mistakes Table

Server-side errors

Wrong	Right	Error
Missing package.json	Create package.json	"could not detect language"
Missing tsconfig.json	Create tsconfig.json	"TsconfigNotFound"
Entrypoint not at src/index.ts	Use src/index.ts	Module won't bundle
indexes in COLUMNS (2nd arg)	indexes in OPTIONS (1st arg)	"reading 'tag'" error
Index without algorithm	algorithm: 'btree'	"reading 'tag'" error
filter({ ownerId })	filter(ownerId)	"does not exist in type 'Range'"
.filter() on unique column	.find() on unique column	TypeError
insert({ ...without id })	insert({ id: 0n, ... })	"Property 'id' is missing"
const id = table.insert(...)	const row = table.insert(...)	.insert() returns ROW, not ID
.unique() + explicit index	Just use .unique()	"name is used for multiple entities"
Index on .primaryKey() column	Don't — already indexed	"name is used for multiple entities"
Same index name in multiple tables	Prefix with table name	"name is used for multiple entities"
.indexName.filter() after removing index	Use .iter() + manual filter	"Cannot read properties of undefined"
Import spacetimedb from index.ts	Import from schema.ts	"Cannot access before initialization"
Multi-column index .filter()	⚠️ BROKEN — use single-column	PANIC or silent empty results
JSON.stringify({ id: row.id })	Convert BigInt first: { id: row.id.toString() }	"Do not know how to serialize a BigInt"
ScheduleAt.Time(timestamp)	ScheduleAt.time(timestamp) (lowercase)	"ScheduleAt.Time is not a function"
ctx.db.foo.myIndexName.filter()	Use exact name: ctx.db.foo.my_index_name.filter()	"Cannot read properties of undefined"
.iter() in views	Use index lookups	Severe performance issues (re-evaluates on any change)
ctx.db in procedures	ctx.withTx(tx => tx.db...)	Procedures need explicit transactions
ctx.myTable in procedure tx	tx.db.myTable	Wrong context variable

Client-side errors

Wrong	Right	Error
@spacetimedb/sdk	spacetimedb	404 / missing subpath
conn.reducers.foo("val")	conn.reducers.foo({ param: "val" })	Wrong reducer syntax
Inline connectionBuilder	useMemo(() => ..., [])	Reconnects every render
const rows = useTable(table)	const [rows, isLoading] = useTable(table)	Tuple destructuring
Optimistic UI updates	Let subscriptions drive state	Desync issues
<SpacetimeDBProvider builder={...}>	connectionBuilder={...}	Wrong prop name

---

2) Table Definition (CRITICAL)

table() takes TWO arguments: table(OPTIONS, COLUMNS)

import { schema, table, t } from "spacetimedb/server";

// ❌ WRONG — indexes in COLUMNS causes "reading 'tag'" error
export const Task = table(
  { name: "task" },
  {
    id: t.u64().primaryKey().autoInc(),
    ownerId: t.identity(),
    indexes: [{ name: "by_owner", algorithm: "btree", columns: ["ownerId"] }], // ❌ WRONG!
  },
);

// ✅ RIGHT — indexes in OPTIONS (first argument)
export const Task = table(
  {
    name: "task",
    public: true,
    indexes: [{ name: "by_owner", algorithm: "btree", columns: ["ownerId"] }],
  },
  {
    id: t.u64().primaryKey().autoInc(),
    ownerId: t.identity(),
    title: t.string(),
    createdAt: t.timestamp(),
  },
);

Column types

t.identity(); // User identity (primary key for per-user tables)
t.u64(); // Unsigned 64-bit integer (use for IDs)
t.string(); // Text
t.bool(); // Boolean
t.timestamp(); // Timestamp (use ctx.timestamp for current time)
t.scheduleAt(); // For scheduled tables only

// Product types (nested objects) — use t.object, NOT t.struct
const Point = t.object("Point", { x: t.i32(), y: t.i32() });

// Sum types (tagged unions) — use t.enum, NOT t.sum
const Shape = t.enum("Shape", { circle: t.i32(), rectangle: Point });
// Values use { tag: 'circle', value: 10 } or { tag: 'rectangle', value: { x: 1, y: 2 } }

// Modifiers
t.string().optional(); // Nullable
t.u64().primaryKey(); // Primary key
t.u64().primaryKey().autoInc(); // Auto-increment primary key

⚠️ BIGINT SYNTAX: All u64, i64, and ID fields use JavaScript BigInt.

• Literals: 0n, 1n, 100n (NOT 0, 1, 100)
• Comparisons: row.id === 5n (NOT row.id === 5)
• Arithmetic: row.count + 1n (NOT row.count + 1)

Auto-increment placeholder

// ✅ MUST provide 0n placeholder for auto-inc fields
ctx.db.task.insert({
  id: 0n,
  ownerId: ctx.sender,
  title: "New",
  createdAt: ctx.timestamp,
});

Insert returns ROW, not ID

// ❌ WRONG
const id = ctx.db.task.insert({ ... });

// ✅ RIGHT
const row = ctx.db.task.insert({ ... });
const newId = row.id;  // Extract .id from returned row

Schema export (CRITICAL)

// At end of schema.ts — schema() takes exactly ONE argument: an object
const spacetimedb = schema({ table1, table2, table3 });
export default spacetimedb;

// ❌ WRONG — never pass tables directly or as multiple args
schema(myTable); // WRONG!
schema(t1, t2, t3); // WRONG!

---

3) Index Access

TypeScript Query Patterns

// 1. PRIMARY KEY — use .pkColumn.find()
const user = ctx.db.user.identity.find(ctx.sender);
const msg = ctx.db.message.id.find(messageId);

// 2. EXPLICIT INDEX — use .indexName.filter(value)
const msgs = [...ctx.db.message.message_room_id.filter(roomId)];

// 3. NO INDEX — use .iter() + manual filter
for (const m of ctx.db.roomMember.iter()) {
  if (m.roomId === roomId) {
    /* ... */
  }
}

Index Definition Syntax

// In table OPTIONS (first argument), not columns
export const Message = table(
  {
    name: "message",
    public: true,
    indexes: [
      { name: "message_room_id", algorithm: "btree", columns: ["roomId"] },
    ],
  },
  {
    id: t.u64().primaryKey().autoInc(),
    roomId: t.u64(),
    // ...
  },
);

Naming conventions

Table names — automatic transformation:

• Schema: table({ name: 'my_messages' })
• Access: ctx.db.myMessages (automatic snake_case → camelCase)

Index names — NO transformation, use EXACTLY as defined:

// Schema definition
indexes: [{ name: 'canvas_member_canvas_id', algorithm: 'btree', columns: ['canvasId'] }]

// ❌ WRONG — don't assume camelCase transformation
ctx.db.canvasMember.canvasMember_canvas_id.filter(...)  // WRONG!
ctx.db.canvasMember.canvasMemberCanvasId.filter(...)    // WRONG!

// ✅ RIGHT — use exact name from schema
ctx.db.canvasMember.canvas_member_canvas_id.filter(...)

⚠️ Index names are used VERBATIM — pick a convention (snake_case or camelCase) and stick with it.

Index naming pattern — use {tableName}_{columnName}:

// ✅ GOOD — unique names across entire module
indexes: [{ name: 'message_room_id', algorithm: 'btree', columns: ['roomId'] }]
indexes: [{ name: 'reaction_message_id', algorithm: 'btree', columns: ['messageId'] }]

// ❌ BAD — will collide if multiple tables use same index name
indexes: [{ name: 'by_owner', ... }]  // in Task table
indexes: [{ name: 'by_owner', ... }]  // in Note table — CONFLICT!

Client-side table names:

• Check generated module_bindings/index.ts for exact export names
• Usage: useTable(tables.MyMessages) or tables.myMessages (varies by SDK version)

Filter vs Find

// Filter takes VALUE directly, not object — returns iterator
const rows = [...ctx.db.task.by_owner.filter(ownerId)];

// Unique columns use .find() — returns single row or undefined
const row = ctx.db.player.identity.find(ctx.sender);

⚠️ Multi-column indexes are BROKEN

// ❌ DON'T — causes PANIC
ctx.db.scores.by_player_level.filter(playerId);

// ✅ DO — use single-column index + manual filter
for (const row of ctx.db.scores.by_player.filter(playerId)) {
  if (row.level === targetLevel) {
    /* ... */
  }
}

---

4) Reducers

Definition syntax (CRITICAL)

Reducer name comes from the export — NOT from a string argument. Use reducer(params, fn) or reducer(fn).

import spacetimedb from './schema';
import { t, SenderError } from 'spacetimedb/server';

// ✅ CORRECT — export const name = spacetimedb.reducer(params, fn)
export const reducer_name = spacetimedb.reducer({ param1: t.string(), param2: t.u64() }, (ctx, { param1, param2 }) => {
  // Validation
  if (!param1) throw new SenderError('param1 required');

  // Access tables via ctx.db
  const row = ctx.db.myTable.primaryKey.find(param2);

  // Mutations
  ctx.db.myTable.insert({ ... });
  ctx.db.myTable.primaryKey.update({ ...row, newField: value });
  ctx.db.myTable.primaryKey.delete(param2);
});

// No params: export const init = spacetimedb.reducer((ctx) => { ... });

// ❌ WRONG — reducer('name', params, fn) does NOT exist
spacetimedb.reducer('reducer_name', { param1: t.string() }, (ctx, { param1 }) => { ... });

Update pattern (CRITICAL)

// ✅ CORRECT — spread existing row, override specific fields
const existing = ctx.db.task.id.find(taskId);
if (!existing) throw new SenderError("Task not found");
ctx.db.task.id.update({
  ...existing,
  title: newTitle,
  updatedAt: ctx.timestamp,
});

// ❌ WRONG — partial update nulls out other fields!
ctx.db.task.id.update({ id: taskId, title: newTitle });

Delete pattern

// Delete by primary key VALUE (not row object)
ctx.db.task.id.delete(taskId); // taskId is the u64 value
ctx.db.player.identity.delete(ctx.sender); // delete by identity

Lifecycle hooks

spacetimedb.clientConnected((ctx) => {
  // ctx.sender is the connecting identity
  // Create/update user record, set online status, etc.
});

spacetimedb.clientDisconnected((ctx) => {
  // Clean up: set offline status, remove ephemeral data, etc.
});

Snake_case to camelCase conversion

• Server: export const do_something = spacetimedb.reducer(...) — name from export
• Client: conn.reducers.doSomething({ ... })

Object syntax required

// ❌ WRONG - positional
conn.reducers.doSomething("value");

// ✅ RIGHT - object
conn.reducers.doSomething({ param: "value" });

---

5) Scheduled Tables

// 1. Define table first (scheduled: () => reducer — pass the exported reducer)
export const CleanupJob = table(
  {
    name: "cleanup_job",
    scheduled: () => run_cleanup, // reducer defined below
  },
  {
    scheduledId: t.u64().primaryKey().autoInc(),
    scheduledAt: t.scheduleAt(),
    targetId: t.u64(), // Your custom data
  },
);

// 2. Define scheduled reducer (receives full row as arg)
export const run_cleanup = spacetimedb.reducer(
  { arg: CleanupJob.rowType },
  (ctx, { arg }) => {
    // arg.scheduledId, arg.targetId available
    // Row is auto-deleted after reducer completes
  },
);

// Schedule a job
import { ScheduleAt } from "spacetimedb";
const futureTime = ctx.timestamp.microsSinceUnixEpoch + 60_000_000n; // 60 seconds
ctx.db.cleanupJob.insert({
  scheduledId: 0n,
  scheduledAt: ScheduleAt.time(futureTime),
  targetId: someId,
});

// Cancel a job by deleting the row
ctx.db.cleanupJob.scheduledId.delete(jobId);

---

6) Timestamps

Server-side

import { Timestamp, ScheduleAt } from "spacetimedb";

// Current time
ctx.db.item.insert({ id: 0n, createdAt: ctx.timestamp });

// Future time (add microseconds)
const future = ctx.timestamp.microsSinceUnixEpoch + 300_000_000n; // 5 minutes

Client-side (CRITICAL)

Timestamps are objects, not numbers:

// ❌ WRONG
const date = new Date(row.createdAt);
const date = new Date(Number(row.createdAt / 1000n));

// ✅ RIGHT
const date = new Date(Number(row.createdAt.microsSinceUnixEpoch / 1000n));

ScheduleAt on client

// ScheduleAt is a tagged union
if (scheduleAt.tag === "Time") {
  const date = new Date(Number(scheduleAt.value.microsSinceUnixEpoch / 1000n));
}

---

7) Data Visibility & Subscriptions

public: true exposes ALL rows to ALL clients.

Scenario	Pattern
Everyone sees all rows	public: true
Users see only their data	Private table + filtered subscription

Subscription patterns (client-side)

// Subscribe to ALL public tables (simplest)
conn.subscriptionBuilder().subscribeToAll();

// Subscribe to specific tables with SQL
conn
  .subscriptionBuilder()
  .subscribe([
    "SELECT * FROM message",
    "SELECT * FROM room WHERE is_public = true",
  ]);

// Handle subscription lifecycle
conn
  .subscriptionBuilder()
  .onApplied(() => console.log("Initial data loaded"))
  .onError((e) => console.error("Subscription failed:", e))
  .subscribeToAll();

Private table + view pattern (RECOMMENDED)

Views are the recommended approach for controlling data visibility. They provide:

• Server-side filtering (reduces network traffic)
• Real-time updates when underlying data changes
• Full control over what data clients can access

⚠️ Do NOT use Row Level Security (RLS) — it is deprecated.

⚠️ CRITICAL: Procedural views (views that compute results in code) can ONLY access data via index lookups, NOT .iter(). If you need a view that scans/filters across many rows (including the entire table), return a query built with the query builder (ctx.from...).

// Private table with index on ownerId
export const PrivateData = table(
  {
    name: "private_data",
    indexes: [{ name: "by_owner", algorithm: "btree", columns: ["ownerId"] }],
  },
  {
    id: t.u64().primaryKey().autoInc(),
    ownerId: t.identity(),
    secret: t.string(),
  },
);

// ❌ BAD — .iter() causes performance issues (re-evaluates on ANY row change)
spacetimedb.view(
  { name: "my_data_slow", public: true },
  t.array(PrivateData.rowType),
  (ctx) => [...ctx.db.privateData.iter()], // Works but VERY slow at scale
);

// ✅ GOOD — index lookup enables targeted invalidation
spacetimedb.view(
  { name: "my_data", public: true },
  t.array(PrivateData.rowType),
  (ctx) => [...ctx.db.privateData.by_owner.filter(ctx.sender)],
);

Query builder view pattern (can scan)

// Query-builder views return a query; the SQL engine maintains the result incrementally.
// This can scan the whole table if needed (e.g. leaderboard-style queries).
spacetimedb.anonymousView(
  { name: "top_players", public: true },
  t.array(Player.rowType),
  (ctx) => ctx.from.player.where((p) => p.score.gt(1000)),
);

ViewContext vs AnonymousViewContext

// ViewContext — has ctx.sender, result varies per user (computed per-subscriber)
spacetimedb.view(
  { name: "my_items", public: true },
  t.array(Item.rowType),
  (ctx) => {
    return [...ctx.db.item.by_owner.filter(ctx.sender)];
  },
);

// AnonymousViewContext — no ctx.sender, same result for everyone (shared, better perf)
spacetimedb.anonymousView(
  { name: "leaderboard", public: true },
  t.array(LeaderboardRow),
  (ctx) => {
    return [...ctx.db.player.by_score.filter(/* top scores */)];
  },
);

Views require explicit subscription:

conn.subscriptionBuilder().subscribe([
  "SELECT * FROM public_table",
  "SELECT * FROM my_data", // Views need explicit SQL!
]);

---

8) React Integration

Key patterns

// Memoize connectionBuilder to prevent reconnects on re-render
const builder = useMemo(
  () =>
    DbConnection.builder()
      .withUri(SPACETIMEDB_URI)
      .withDatabaseName(MODULE_NAME)
      .withToken(localStorage.getItem("auth_token") || undefined)
      .onConnect(onConnect)
      .onConnectError(onConnectError),
  [], // Empty deps - only create once
);

// useTable returns tuple [rows, isLoading]
const [rows, isLoading] = useTable(tables.myTable);

// Compare identities using toHexString()
const isOwner = row.ownerId.toHexString() === myIdentity.toHexString();

---

9) Procedures (Beta)

Procedures are for side effects (HTTP requests, etc.) that reducers can't do.

⚠️ Procedures are currently in beta. API may change.

Defining a procedure

Procedure name comes from the export — NOT from a string argument. Use procedure(params, ret, fn) or procedure(ret, fn).

// ✅ CORRECT — export const name = spacetimedb.procedure(params, ret, fn)
export const fetch_external_data = spacetimedb.procedure(
  { url: t.string() },
  t.string(), // return type
  (ctx, { url }) => {
    const response = ctx.http.fetch(url);
    return response.text();
  },
);

Database access in procedures

⚠️ CRITICAL: Procedures don't have ctx.db. Use ctx.withTx() for database access.

spacetimedb.procedure({ url: t.string() }, t.unit(), (ctx, { url }) => {
  // Fetch external data (outside transaction)
  const response = ctx.http.fetch(url);
  const data = response.text();

  // ❌ WRONG — ctx.db doesn't exist in procedures
  ctx.db.myTable.insert({ ... });

  // ✅ RIGHT — use ctx.withTx() for database access
  ctx.withTx(tx => {
    tx.db.myTable.insert({
      id: 0n,
      content: data,
      fetchedAt: tx.timestamp,
      fetchedBy: tx.sender,
    });
  });

  return {};
});

Key differences from reducers

Reducers	Procedures
ctx.db available directly	Must use ctx.withTx(tx => tx.db...)
Automatic transaction	Manual transaction management
No HTTP/network	ctx.http.fetch() available
No return values to caller	Can return data to caller

---

10) Project Structure

Server (backend/spacetimedb/)

src/schema.ts   → Tables, export spacetimedb
src/index.ts    → Reducers, lifecycle, import schema
package.json    → { "type": "module", "dependencies": { "spacetimedb": "^1.11.0" } }
tsconfig.json   → Standard config

Avoiding circular imports

schema.ts → defines tables AND exports spacetimedb
index.ts  → imports spacetimedb from ./schema, defines reducers

Client (client/)

src/module_bindings/ → Generated (spacetime generate)
src/main.tsx         → Provider, connection setup
src/App.tsx          → UI components
src/config.ts        → MODULE_NAME, SPACETIMEDB_URI

---

11) Commands

# Start local server
spacetime start

# Publish module
spacetime publish <module-name> --module-path <backend-dir>

# Clear database and republish
spacetime publish <module-name> --clear-database -y --module-path <backend-dir>

# Generate bindings
spacetime generate --lang typescript --out-dir <client>/src/module_bindings --module-path <backend-dir>

# View logs
spacetime logs <module-name>

---

12) Hard Requirements

TypeScript-specific:

1. schema({ table }) — takes exactly one object; never schema(table) or schema(t1, t2, t3)
2. Reducer/procedure names from exports — export const name = spacetimedb.reducer(params, fn); never reducer('name', ...)
3. Reducer calls use object syntax — { param: 'value' } not positional args
4. Import DbConnection from ./module_bindings — not from spacetimedb
5. DO NOT edit generated bindings — regenerate with spacetime generate
6. Indexes go in OPTIONS (1st arg) — not in COLUMNS (2nd arg) of table()
7. Use BigInt for u64/i64 fields — 0n, 1n, not 0, 1
8. Reducers are transactional — they do not return data
9. Reducers must be deterministic — no filesystem, network, timers, random
10. Views should use index lookups — .iter() causes severe performance issues
11. Procedures need ctx.withTx() — ctx.db doesn't exist in procedures
12. Sum type values — use { tag: 'variant', value: payload } not { variant: payload }