You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The README was significantly out of date. This overhaul brings it in
line with the current docs and product state.
## What changed
**Content updates:**
- "What is SpacetimeDB" now mentions all 4 module languages (Rust, C#,
TypeScript, C++) instead of only Rust
- Removed the smart contracts comparison (outdated framing)
- Updated BitCraft description to match current docs wording
- Shortened the architecture description to be punchier
**New Quick Start section:**
- 5-step flow: install, login, init, dev, publish
- Introduces `spacetime dev` (the primary local development experience)
- Introduces `spacetime publish` to Maincloud
- Much more approachable than the old "Installation" wall of text
**New "How It Works" section:**
- Rust module code example showing tables and reducers
- TypeScript client code example showing `useTable` subscriptions
- Shows the core value prop in < 20 lines of code
**Language support:**
- Added TypeScript and C++ as server module languages
- Added Unreal Engine (C++) as a client SDK
- Listed all supported web frameworks (React, Next.js, Vue, Svelte,
Angular, Node.js, Bun, Deno)
- Fixed all doc links to current URL patterns (`/docs/quickstarts/...`)
**Build from source:**
- Collapsed into expandable `<details>` sections (macOS/Linux and
Windows)
- Removed duplicate Git for Windows instructions
- Still complete, just not the first thing you see
**Badges:**
- Added npm download count badge for the TypeScript SDK
**License:**
- Shortened to essentials with link to full license file
---------
Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
## What is [SpacetimeDB](https://spacetimedb.com)?
68
+
## What is SpacetimeDB?
67
69
68
-
You can think of SpacetimeDB as both a database and server combined into one.
70
+
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.
69
71
70
-
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."
72
+
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.
71
73
72
-
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.
74
+
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.
73
75
74
-
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.
76
+
This means that you can write your entire application in a single languageand 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.
@@ -80,214 +82,173 @@ This means that you can write your entire application in a single language, Rust
80
82
</figcaption>
81
83
</figure>
82
84
83
-
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.
84
-
85
-
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.
86
-
87
-
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.
88
-
89
-
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.
90
-
91
-
## Installation
92
-
93
-
You can run SpacetimeDB as a standalone database server via the `spacetime` CLI tool.
94
-
Install instructions for supported platforms are outlined below.
95
-
The same install instructions can be found on our website at https://spacetimedb.com/install.
96
-
97
-
#### Install on macOS
98
-
99
-
Installing on macOS is as simple as running our install script. After that you can use the spacetime command to manage versions.
100
-
101
-
```bash
102
-
curl -sSf https://install.spacetimedb.com | sh
103
-
```
85
+
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.
104
86
105
-
#### Install on Linux
87
+
##Quick Start
106
88
107
-
Installing on Linux is as simple as running our install script. After that you can use the spacetime command to manage versions.
89
+
### 1. Install
108
90
109
91
```bash
92
+
# macOS / Linux
110
93
curl -sSf https://install.spacetimedb.com | sh
111
-
```
112
-
113
-
#### Install on Windows
114
94
115
-
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.
116
-
117
-
```ps1
95
+
# Windows (PowerShell)
118
96
iwr https://windows.spacetimedb.com -useb | iex
119
97
```
120
98
121
-
#### Installing from Source
122
-
123
-
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.
124
-
125
-
##### MacOS + Linux
126
-
127
-
Installing on macOS + Linux is pretty straightforward. First we are going to build all of the binaries that we need:
99
+
### 2. Log in
128
100
129
101
```bash
130
-
# Install rustup, you can skip this step if you have cargo and the wasm32-unknown-unknown target already installed.
At this stage you'll need to add ~/.local/bin to your path if you haven't already.
105
+
This opens a browser to authenticate with GitHub. Your identity is linked to your account so you can publish databases.
150
106
151
-
```
152
-
# Please add the following line to your shell configuration and open a new shell session:
153
-
export PATH="$HOME/.local/bin:$PATH"
107
+
### 3. Start developing
154
108
109
+
```bash
110
+
spacetime dev --template chat-react-ts
155
111
```
156
112
157
-
Then finally set your SpacetimeDB version:
158
-
```
113
+
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.
159
114
160
-
# Then, in a new shell, set the current version:
161
-
spacetime version use $STDB_VERSION
115
+
## How It Works
162
116
163
-
# If STDB_VERSION is not set anymore then you can use the following command to list your versions:
164
-
spacetime version list
165
-
```
117
+
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.
166
118
167
-
You can verify that the correct version has been installed via `spacetime --version`.
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.
141
+
On the client side, subscribe and get live updates:
172
142
173
-
In a Git for Windows shell you should have something that looks like this:
174
-
```
175
-
$ which perl
176
-
/c/Strawberry/perl/bin/perl
177
-
$ which openssl
178
-
/mingw64/bin/openssl
179
-
$ which cargo
180
-
/c/Users/<user>/.cargo/bin/cargo
143
+
```typescript
144
+
const [messages] =useTable(tables.message);
145
+
// messages updates automatically when the server state changes.
146
+
// No polling. No refetching.
181
147
```
182
148
183
-
If that looks correct then you're ready to proceed!
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!
# 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!
241
-
# %USERPROFILE%\AppData\Local\SpacetimeDB
242
-
243
-
# Set the current version
244
-
spacetime version use $STDB_VERSION
245
190
```
246
191
247
-
You can verify that the correct version has been installed via `spacetime --version`.
248
-
249
-
#### Running with Docker
192
+
Then install the binaries:
250
193
251
-
If you prefer to run Spacetime in a container, you can use the following command to start a new instance.
194
+
<details>
195
+
<summary>macOS / Linux</summary>
252
196
253
197
```bash
254
-
docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start
255
-
```
256
-
257
-
## Documentation
258
-
259
-
For more information about SpacetimeDB, getting started guides, game development guides, and reference material please see our [documentation](https://spacetimedb.com/docs).
198
+
mkdir -p ~/.local/bin
199
+
STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')"
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).
206
+
# Add to your shell config if not already present:
207
+
export PATH="$HOME/.local/bin:$PATH"
264
208
265
-
In summary there are only 4 steps to getting started with SpacetimeDB.
209
+
# Set the active version:
210
+
spacetime version use $STDB_VERSION
211
+
```
212
+
</details>
266
213
267
-
1. Install the `spacetime` CLI tool.
268
-
2. Start a SpacetimeDB standalone node with `spacetime start`.
269
-
3. Write and upload a module in one of our supported module languages.
270
-
4. Connect to the database with one of our client libraries.
214
+
<details>
215
+
<summary>Windows (PowerShell)</summary>
271
216
272
-
You can see a summary of the supported languages below with a link to the getting started guide for each.
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.
249
+
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.
250
+
251
+
**Why did we choose this license?**
252
+
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.
292
253
293
-
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.
254
+
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).
0 commit comments