mirror of
https://github.com/clockworklabs/SpacetimeDB.git
synced 2026-05-13 03:08:40 -04:00
Tyler Cloutier
73881e38f7
# Description of Changes Major documentation overhaul focusing on tables, column types, and indexes. **Quickstart Guides:** - Updated React, TypeScript, Rust, and C# quickstarts with table/reducer examples - Fixed CLI syntax (positional `--database` argument) - Improved template consistency across languages **Tables Documentation:** - Added "Why Tables" section explaining table-oriented design philosophy (tables as fundamental unit, system tables, data-oriented design principles) - Added "Physical and Logical Independence" section explaining how subscription queries use the relational model independently of physical storage - Added brief sections linking to related pages (Visibility, Constraints, Schedule Tables) - Renamed "Scheduled Tables" to "Schedule Tables" throughout (tables store schedules; reducers are scheduled) **Column Types:** - Split into dedicated page with unified type reference table - Added "Representing Collections" section (Vec/Array vs table tradeoffs) - Added "Binary Data and Files" section for Vec<u8> storage patterns - Added "Type Performance" section (smaller types, fixed-size types, column ordering for alignment) - Added complete example struct demonstrating all type categories - Renamed "Structured" category to "Composite" **Indexes:** - Complete rewrite with textbook-style documentation - Added "When to Use Indexes" guidance - Documented single-column and multi-column index syntax (field-level and table-level) - Comprehensive range query examples with correct TypeScript `Range` class syntax - Explained multi-column index prefix matching semantics - Added index-accelerated deletion examples - Included index design guidelines **Styling:** - Added CSS for table border radius and row separators - Created Check component for green checkmarks in tables # API and ABI breaking changes None. Documentation only. # Expected complexity level and risk 1 - Documentation changes only, no code changes. # Testing - [ ] Verify docs build without errors - [ ] Review rendered pages for formatting issues - [ ] Confirm code examples are syntactically correct --------- Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com> Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com> Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com> Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
80 lines
2.2 KiB
Plaintext
80 lines
2.2 KiB
Plaintext
---
|
|
description: "⛔ MANDATORY: Core SpacetimeDB concepts (all languages)."
|
|
globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.rs,**/*.cs
|
|
alwaysApply: true
|
|
---
|
|
# SpacetimeDB Rules (All Languages)
|
|
|
|
> **Last updated:** 2026-01-06
|
|
|
|
## Language-Specific Rules
|
|
|
|
| Language | Rule File |
|
|
|----------|-----------|
|
|
| **TypeScript/React** | `spacetimedb-typescript.mdc` (MANDATORY) |
|
|
| **Rust** | `spacetimedb-rust.mdc` (MANDATORY) |
|
|
| **C#** | `spacetimedb-csharp.mdc` (MANDATORY) |
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Start local SpacetimeDB
|
|
spacetime start
|
|
|
|
# Publish module
|
|
spacetime publish <db-name> --project-path <module-path>
|
|
|
|
# Clear and republish
|
|
spacetime publish <db-name> --clear-database -y --project-path <module-path>
|
|
|
|
# Generate client bindings
|
|
spacetime generate --lang <lang> --out-dir <out> --project-path <module-path>
|
|
|
|
# View logs
|
|
spacetime logs <db-name>
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|