From dc72947bbd809be55b3749973e750707ac1cd743 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Sat, 28 Feb 2026 02:23:25 -0500 Subject: [PATCH 1/4] Overhaul README with up-to-date content Major changes: - Update 'What is SpacetimeDB' to mention all 4 module languages (Rust, C#, TypeScript, C++) instead of only Rust - Replace verbose installation section with concise quick start flow: install, login, init, dev, publish - Add spacetime dev workflow (the primary local dev experience) - Add Maincloud deployment step - Add 'How It Works' section with Rust module + TypeScript client code examples showing tables, reducers, and subscriptions - Update language support tables to include TypeScript modules, C++ modules, and Unreal Engine SDK - List all supported client frameworks (React, Next.js, Vue, Svelte, Angular, Node.js, Bun, Deno) - Fix doc links to current URL patterns (/docs/quickstarts/...) - Collapse build-from-source instructions into expandable details sections (macOS/Linux and Windows) to reduce visual clutter - Remove stale smart contracts comparison - Remove duplicate Git for Windows instructions - Add npm download badge - Shorten license section (link to FAQ for details) --- README.md | 277 ++++++++++++++++++++++++------------------------------ 1 file changed, 124 insertions(+), 153 deletions(-) diff --git a/README.md b/README.md index 3167f9ac3ed..66e6868ca78 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@   +   +

@@ -63,15 +65,13 @@
-## What is [SpacetimeDB](https://spacetimedb.com)? - -You can think of SpacetimeDB as both a database and server combined into one. +## What is SpacetimeDB? -It is a relational database system that lets you upload your application logic directly into the database by way of fancy stored procedures called "modules." +SpacetimeDB is a database that is also a server. You upload your application logic directly into the database, and clients connect to it without any server in between. -Instead of deploying a web or game server that sits in between your clients and your database, your clients connect directly to the database and execute your application logic inside the database itself. You can write all of your permission and authorization logic right inside your module just as you would in a normal server. +Write your schema and business logic as a **module** in [Rust](https://spacetimedb.com/docs/quickstarts/rust), [C#](https://spacetimedb.com/docs/quickstarts/c-sharp), [TypeScript](https://spacetimedb.com/docs/quickstarts/typescript), or [C++](https://spacetimedb.com/docs/quickstarts/cpp). SpacetimeDB compiles it, runs it inside the database, and automatically synchronizes state to connected clients in real-time. -This means that you can write your entire application in a single language, Rust, and deploy it as a single binary. No more microservices, no more containers, no more Kubernetes, no more Docker, no more VMs, no more DevOps, no more infrastructure, no more ops, no more servers. +No separate web server. No REST API. No caching layer. No infrastructure to manage.

SpacetimeDB Architecture @@ -80,214 +80,185 @@ This means that you can write your entire application in a single language, Rust
-It's actually similar to the idea of smart contracts, except that SpacetimeDB is a database, has nothing to do with blockchain, and is orders of magnitude faster than any smart contract system. - -So fast, in fact, that the entire backend of our MMORPG [BitCraft Online](https://bitcraftonline.com) is just a SpacetimeDB module. We don't have any other servers or services running, which means that everything in the game, all of the chat messages, items, resources, terrain, and even the locations of the players are stored and processed by the database before being synchronized out to all of the clients in real-time. - -SpacetimeDB is optimized for maximum speed and minimum latency rather than batch processing or OLAP workloads. It is designed to be used for real-time applications like games, chat, and collaboration tools. - -This speed and latency is achieved by holding all of application state in memory, while persisting the data in a write-ahead-log (WAL) which is used to recover application state. - -## Installation +SpacetimeDB is optimized for maximum speed and minimum latency. All application state is held in memory for fast access, while a commit log on disk provides durability and crash recovery. The entire backend of our MMORPG [BitCraft Online](https://bitcraftonline.com) runs as a single SpacetimeDB module: chat, items, terrain, player positions, everything, synchronized to thousands of players in real-time. -You can run SpacetimeDB as a standalone database server via the `spacetime` CLI tool. -Install instructions for supported platforms are outlined below. -The same install instructions can be found on our website at https://spacetimedb.com/install. +## Quick Start -#### Install on macOS - -Installing on macOS is as simple as running our install script. After that you can use the spacetime command to manage versions. +### 1. Install ```bash +# macOS / Linux curl -sSf https://install.spacetimedb.com | sh -``` -#### Install on Linux +# Windows (PowerShell) +iwr https://windows.spacetimedb.com -useb | iex +``` -Installing on Linux is as simple as running our install script. After that you can use the spacetime command to manage versions. +### 2. Log in ```bash -curl -sSf https://install.spacetimedb.com | sh +spacetime login ``` -#### Install on Windows +This opens a browser to authenticate with GitHub. Your identity is linked to your account so you can publish databases. -Installing on Windows is as simple as pasting the snippet below into PowerShell. If you would like to use WSL instead, please follow the Linux install instructions. +### 3. Create a project -```ps1 -iwr https://windows.spacetimedb.com -useb | iex +```bash +spacetime init --lang rust my-project +cd my-project ``` -#### Installing from Source - -A quick note on installing from source: we recommend that you don't install from source unless there is a feature that is available in `master` that hasn't been released yet, otherwise follow the official installation instructions. +Supported module languages: `rust`, `csharp`, `typescript`, `cpp` -##### MacOS + Linux - -Installing on macOS + Linux is pretty straightforward. First we are going to build all of the binaries that we need: +### 4. Develop locally ```bash -# Install rustup, you can skip this step if you have cargo and the wasm32-unknown-unknown target already installed. -curl https://sh.rustup.rs -sSf | sh -# Clone SpacetimeDB -git clone https://github.com/clockworklabs/SpacetimeDB -# Build and install the CLI -cd SpacetimeDB -cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli - -# Create directories -mkdir -p ~/.local/bin -export STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')" -mkdir -p ~/.local/share/spacetime/bin/$STDB_VERSION - -# Install the update binary -cp target/release/spacetimedb-update ~/.local/bin/spacetime -cp target/release/spacetimedb-cli ~/.local/share/spacetime/bin/$STDB_VERSION -cp target/release/spacetimedb-standalone ~/.local/share/spacetime/bin/$STDB_VERSION +spacetime dev ``` -At this stage you'll need to add ~/.local/bin to your path if you haven't already. +This starts a local SpacetimeDB instance, publishes your module, watches for file changes, and automatically rebuilds and republishes on save. -``` -# Please add the following line to your shell configuration and open a new shell session: -export PATH="$HOME/.local/bin:$PATH" +### 5. Publish to the cloud +```bash +spacetime publish my-database ``` -Then finally set your SpacetimeDB version: +This deploys your module to [Maincloud](https://spacetimedb.com/docs/how-to/deploy/maincloud), the fully managed SpacetimeDB cloud. It scales to zero when idle and you only pay for what you use. See [pricing](https://spacetimedb.com/pricing) for details. + +## How It Works + +SpacetimeDB modules define **tables** (your data) and **reducers** (your logic). Clients connect, call reducers, and subscribe to tables. When data changes, SpacetimeDB pushes updates to subscribed clients automatically. + +```rust +// Define a table +#[spacetimedb::table(accessor = messages, public)] +pub struct Message { + #[primary_key] + #[auto_inc] + id: u64, + sender: Identity, + text: String, +} + +// Define a reducer (your API endpoint) +#[spacetimedb::reducer] +pub fn send_message(ctx: &ReducerContext, text: String) { + ctx.db.messages().insert(Message { + id: 0, + sender: ctx.sender, + text, + }); +} ``` -# Then, in a new shell, set the current version: -spacetime version use $STDB_VERSION +On the client side, subscribe and get live updates: -# If STDB_VERSION is not set anymore then you can use the following command to list your versions: -spacetime version list +```typescript +const [messages] = useTable(tables.message); +// messages updates automatically when the server state changes. +// No polling. No refetching. ``` -You can verify that the correct version has been installed via `spacetime --version`. - -##### Windows - -Building on windows is a bit more complicated. You'll need a slightly different version of perl compared to what comes pre-bundled in most Windows terminals. We recommend [Strawberry Perl](https://strawberryperl.com/). You may also need access to an `openssl` binary which actually comes pre-installed with [Git for Windows](https://git-scm.com/downloads/win). Also, you'll need to install [rustup](https://rustup.rs/) for Windows. - -In a Git for Windows shell you should have something that looks like this: -``` -$ which perl -/c/Strawberry/perl/bin/perl -$ which openssl -/mingw64/bin/openssl -$ which cargo -/c/Users//.cargo/bin/cargo -``` - -If that looks correct then you're ready to proceed! - -```powershell -# Clone SpacetimeDB -git clone https://github.com/clockworklabs/SpacetimeDB +## Language Support -# Build and install the CLI -cd SpacetimeDB -cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli +### Server Modules -# Create directories -$stdbDir = "$HOME\AppData\Local\SpacetimeDB" -$stdbVersion = & ".\target\release\spacetimedb-cli" --version | Select-String -Pattern 'spacetimedb tool version ([0-9.]+);' | ForEach-Object { $_.Matches.Groups[1].Value } -New-Item -ItemType Directory -Path "$stdbDir\bin\$stdbVersion" -Force | Out-Null +Write your database logic in any of these languages: -# Install the update binary -Copy-Item "target\release\spacetimedb-update.exe" "$stdbDir\spacetime.exe" -Copy-Item "target\release\spacetimedb-cli.exe" "$stdbDir\bin\$stdbVersion\" -Copy-Item "target\release\spacetimedb-standalone.exe" "$stdbDir\bin\$stdbVersion\" +| Language | Quickstart | +|----------|-----------| +| **Rust** | [Get started](https://spacetimedb.com/docs/quickstarts/rust) | +| **C#** | [Get started](https://spacetimedb.com/docs/quickstarts/c-sharp) | +| **TypeScript** | [Get started](https://spacetimedb.com/docs/quickstarts/typescript) | +| **C++** | [Get started](https://spacetimedb.com/docs/quickstarts/cpp) | -``` +### Client SDKs -Now add the directory we just created to your path. We recommend adding it to the system path because then it will be available to all of your applications (including Unity3D). After you do this, restart your shell! +Connect from any of these platforms: -``` -%USERPROFILE%\AppData\Local\SpacetimeDB -``` +| SDK | Quickstart | +|-----|-----------| +| **TypeScript** (React, Next.js, Vue, Svelte, Angular, Node.js, Bun, Deno) | [Get started](https://spacetimedb.com/docs/quickstarts/react) | +| **Rust** | [Get started](https://spacetimedb.com/docs/quickstarts/rust) | +| **C#** (standalone and Unity) | [Get started](https://spacetimedb.com/docs/quickstarts/c-sharp) | +| **C++** (Unreal Engine) | [Get started](https://spacetimedb.com/docs/quickstarts/cpp) | -Then finally, open a new shell and use the installed SpacetimeDB version: -``` -spacetime version use $stdbVersion +## Running with Docker -# If stdbVersion is no longer set, list versions using the following command: -spacetime version list +```bash +docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start ``` -You can verify that the correct version has been installed via `spacetime --version`. +## Building from Source -If you're using Git for Windows you can follow these instructions instead: +If you need features from `master` that have not been released yet: ```bash -# Clone SpacetimeDB +# Prerequisites: Rust toolchain with wasm32-unknown-unknown target +curl https://sh.rustup.rs -sSf | sh + git clone https://github.com/clockworklabs/SpacetimeDB -# Build and install the CLI cd SpacetimeDB -# Build the CLI binaries - this takes a while on windows so go grab a coffee :) cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli - -# Create directories -export STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')" -mkdir -p ~/AppData/Local/SpacetimeDB/bin/$STDB_VERSION - -# Install the update binary -cp target/release/spacetimedb-update ~/AppData/Local/SpacetimeDB/spacetime -cp target/release/spacetimedb-cli ~/AppData/Local/SpacetimeDB/bin/$STDB_VERSION -cp target/release/spacetimedb-standalone ~/AppData/Local/SpacetimeDB/bin/$STDB_VERSION - -# Now add the directory we just created to your path. We recommend adding it to the system path because then it will be available to all of your applications (including Unity3D). After you do this, restart your shell! -# %USERPROFILE%\AppData\Local\SpacetimeDB - -# Set the current version -spacetime version use $STDB_VERSION ``` -You can verify that the correct version has been installed via `spacetime --version`. - -#### Running with Docker +Then install the binaries: -If you prefer to run Spacetime in a container, you can use the following command to start a new instance. +
+macOS / Linux ```bash -docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start -``` - -## Documentation - -For more information about SpacetimeDB, getting started guides, game development guides, and reference material please see our [documentation](https://spacetimedb.com/docs). +mkdir -p ~/.local/bin +STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')" +mkdir -p ~/.local/share/spacetime/bin/$STDB_VERSION -## Getting Started +cp target/release/spacetimedb-update ~/.local/bin/spacetime +cp target/release/spacetimedb-cli ~/.local/share/spacetime/bin/$STDB_VERSION +cp target/release/spacetimedb-standalone ~/.local/share/spacetime/bin/$STDB_VERSION -We've prepared several getting started guides in each of our supported languages to help you get up and running with SpacetimeDB as quickly as possible. You can find them on our [docs page](https://spacetimedb.com/docs). +# Add to your shell config if not already present: +export PATH="$HOME/.local/bin:$PATH" -In summary there are only 4 steps to getting started with SpacetimeDB. +# Set the active version: +spacetime version use $STDB_VERSION +``` +
-1. Install the `spacetime` CLI tool. -2. Start a SpacetimeDB standalone node with `spacetime start`. -3. Write and upload a module in one of our supported module languages. -4. Connect to the database with one of our client libraries. +
+Windows (PowerShell) -You can see a summary of the supported languages below with a link to the getting started guide for each. +```powershell +$stdbDir = "$HOME\AppData\Local\SpacetimeDB" +$stdbVersion = & ".\target\release\spacetimedb-cli" --version | + Select-String -Pattern 'spacetimedb tool version ([0-9.]+);' | + ForEach-Object { $_.Matches.Groups[1].Value } +New-Item -ItemType Directory -Path "$stdbDir\bin\$stdbVersion" -Force | Out-Null -## Language Support +Copy-Item "target\release\spacetimedb-update.exe" "$stdbDir\spacetime.exe" +Copy-Item "target\release\spacetimedb-cli.exe" "$stdbDir\bin\$stdbVersion\" +Copy-Item "target\release\spacetimedb-standalone.exe" "$stdbDir\bin\$stdbVersion\" -You can write SpacetimeDB modules in several popular languages, with more to come in the future! +# Add to your system PATH: %USERPROFILE%\AppData\Local\SpacetimeDB +# Then in a new shell: +spacetime version use $stdbVersion +``` +
-#### Serverside Libraries +Verify with `spacetime --version`. -- [Rust](https://spacetimedb.com/docs/modules/rust/quickstart) -- [C#](https://spacetimedb.com/docs/modules/c-sharp/quickstart) +## Documentation -#### Client Libraries +Full documentation is available at **[spacetimedb.com/docs](https://spacetimedb.com/docs)**, including: -- [Rust](https://spacetimedb.com/docs/sdks/rust/quickstart) -- [C#](https://spacetimedb.com/docs/sdks/c-sharp/quickstart) -- [Typescript](https://spacetimedb.com/docs/sdks/typescript/quickstart) +- [Quickstart guides](https://spacetimedb.com/docs) for every supported language and framework +- [Core concepts](https://spacetimedb.com/docs/core-concepts): tables, reducers, subscriptions, authentication +- [Tutorials](https://spacetimedb.com/docs/tutorials/chat-app): chat app, Unity multiplayer, Unreal Engine multiplayer +- [Deployment guide](https://spacetimedb.com/docs/how-to/deploy/maincloud): publishing to Maincloud +- [CLI reference](https://spacetimedb.com/docs/reference/cli-reference) +- [SQL reference](https://spacetimedb.com/docs/reference/sql-reference) ## License -SpacetimeDB is licensed under the BSL 1.1 license. This is not an open source or free software license, however, it converts to the AGPL v3.0 license with a linking exception after a few years. - -Note that the AGPL v3.0 does not typically include a linking exception. We have added a custom linking exception to the AGPL license for SpacetimeDB. Our motivation for choosing a free software license is to ensure that contributions made to SpacetimeDB are propagated back to the community. We are expressly not interested in forcing users of SpacetimeDB to open source their own code if they link with SpacetimeDB, so we needed to include a linking exception. +SpacetimeDB is licensed under the [Business Source License 1.1 (BSL)](LICENSE.txt). It converts to the AGPL v3.0 with a linking exception after a few years. The linking exception means you are **not** required to open-source your own code if you use SpacetimeDB. You only need to contribute back changes to SpacetimeDB itself. From 130cc3e120999f5de21ab34b78a66302415e2145 Mon Sep 17 00:00:00 2001 From: Tyler Cloutier Date: Sun, 1 Mar 2026 11:54:02 -0500 Subject: [PATCH 2/4] Apply suggestions from code review Signed-off-by: Tyler Cloutier --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 66e6868ca78..2ffcffda6a3 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@     - +

@@ -67,11 +67,13 @@ ## What is SpacetimeDB? -SpacetimeDB is a database that is also a server. You upload your application logic directly into the database, and clients connect to it without any server in between. +SpacetimeDB is a relational database that is also a server. You upload your application logic directly into the database, and clients connect to it without any server in between. Write your schema and business logic as a **module** in [Rust](https://spacetimedb.com/docs/quickstarts/rust), [C#](https://spacetimedb.com/docs/quickstarts/c-sharp), [TypeScript](https://spacetimedb.com/docs/quickstarts/typescript), or [C++](https://spacetimedb.com/docs/quickstarts/cpp). SpacetimeDB compiles it, runs it inside the database, and automatically synchronizes state to connected clients in real-time. -No separate web server. No REST API. No caching layer. No infrastructure to manage. +Instead of deploying a web or game server that sits in between your clients and your database, your clients connect directly to the database and execute your application logic in your module. You can write all of your permission and authorization logic right inside your module just as you would in a normal server. + +This means that you can write your entire application in a single language and deploy it as a single binary. No more separate webserver, no more containers, no more Kubernetes, no more VMs, no more DevOps, no more caching later. Zero infrastructure to manage.

SpacetimeDB Architecture @@ -80,7 +82,7 @@ No separate web server. No REST API. No caching layer. No infrastructure to mana
-SpacetimeDB is optimized for maximum speed and minimum latency. All application state is held in memory for fast access, while a commit log on disk provides durability and crash recovery. The entire backend of our MMORPG [BitCraft Online](https://bitcraftonline.com) runs as a single SpacetimeDB module: chat, items, terrain, player positions, everything, synchronized to thousands of players in real-time. +SpacetimeDB is optimized for maximum speed and minimum latency. SpacetimeDB provides all the ACID guarantees of a traditional RDBMS, with all the speed of an optimized web server. All application state is held in memory for fast access, while a commit log on disk provides durability and crash recovery. The entire backend of our MMORPG [BitCraft Online](https://bitcraftonline.com) runs as a single SpacetimeDB module: chat, items, terrain, player positions, everything, synchronized to thousands of players in real-time. ## Quick Start @@ -262,3 +264,8 @@ Full documentation is available at **[spacetimedb.com/docs](https://spacetimedb. ## License SpacetimeDB is licensed under the [Business Source License 1.1 (BSL)](LICENSE.txt). It converts to the AGPL v3.0 with a linking exception after a few years. The linking exception means you are **not** required to open-source your own code if you use SpacetimeDB. You only need to contribute back changes to SpacetimeDB itself. + +**Why did we choose this license?** +We chose to license SpacetimeDB under the MariaDB Business Source License for 4 years because we can't compete with AWS while also building our products for them. + +We chose GPLv3 with linking exception as the open source license because we want contributions merged back into mainline (just like Linux), but we don't want to make anyone else open source their own code (i.e. linking exception). From 64d28fea9808ccfe7c5adc98c65f96b13535e223 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Sun, 1 Mar 2026 11:58:09 -0500 Subject: [PATCH 3/4] Address review: simplify Quick Start to use spacetime dev --template - Collapse steps 3+4 into a single 'Start developing' step - Use spacetime dev --template chat-react-ts as the entry point - Fix description: dev publishes to Maincloud, does not start a local server - Renumber step 5 -> 4 --- README.md | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 2ffcffda6a3..f0b46a8136d 100644 --- a/README.md +++ b/README.md @@ -104,24 +104,15 @@ spacetime login This opens a browser to authenticate with GitHub. Your identity is linked to your account so you can publish databases. -### 3. Create a project +### 3. Start developing ```bash -spacetime init --lang rust my-project -cd my-project +spacetime dev --template chat-react-ts ``` -Supported module languages: `rust`, `csharp`, `typescript`, `cpp` +This publishes your module, watches for file changes, and automatically rebuilds and republishes on save. -### 4. Develop locally - -```bash -spacetime dev -``` - -This starts a local SpacetimeDB instance, publishes your module, watches for file changes, and automatically rebuilds and republishes on save. - -### 5. Publish to the cloud +### 4. Publish to the cloud ```bash spacetime publish my-database From e02666d27c507147cfc57912aaac698a4e2592eb Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Sun, 1 Mar 2026 12:03:23 -0500 Subject: [PATCH 4/4] Simplify Quick Start: remove redundant publish step spacetime dev already publishes to Maincloud by default, so a separate 'spacetime publish' step is unnecessary. Consolidate into a single 3-step flow: install, login, dev. --- README.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/README.md b/README.md index f0b46a8136d..270d123af20 100644 --- a/README.md +++ b/README.md @@ -110,15 +110,7 @@ This opens a browser to authenticate with GitHub. Your identity is linked to you spacetime dev --template chat-react-ts ``` -This publishes your module, watches for file changes, and automatically rebuilds and republishes on save. - -### 4. Publish to the cloud - -```bash -spacetime publish my-database -``` - -This deploys your module to [Maincloud](https://spacetimedb.com/docs/how-to/deploy/maincloud), the fully managed SpacetimeDB cloud. It scales to zero when idle and you only pay for what you use. See [pricing](https://spacetimedb.com/pricing) for details. +That is it. This creates a project from a template, publishes it to [Maincloud](https://spacetimedb.com/docs/how-to/deploy/maincloud), and watches for file changes, automatically rebuilding and republishing on save. See [pricing](https://spacetimedb.com/pricing) for details. ## How It Works