Skip to content

Commit aca374a

Browse files
feat: Quickstart and client for Plain JS Script Tags (#4161)
# Description of Changes The PR implements the following updates: - Create a quickstart guide and client support for using SpacetimeDB directly in browser with script tags - A template to easily work with/test the implementation and get started with script tags The bundle is served via `https://unpkg.com/spacetimedb@latest/dist/browser.bundle.js`, which only works after the package is published to npm, therefore to test locally we can use the `browser-ts` template and local bundle: 1. Build local bundle ``` cd crates/bindings-typescript pnpm install pnpm build ``` 2. Use local bundle built in template`index.html` (swap the URL from `unpkg`) ```diff - <script src="https://unpkg.com/spacetimedb@latest/dist/browser.bundle.js"></script> + <script src="../../crates/bindings-typescript/dist/browser.bundle.js"></script> ``` 3. Open `browser-ts/index.html` directly in browser along with `spacetime start` + publish the module `spacetime publish --project-path spacetimedb browser-ts` # Screenshots <img width="1106" height="707" alt="image" src="https://github.com/user-attachments/assets/715bea26-f54b-42be-97f9-79dcd57d153f" /> <img width="1490" height="855" alt="image" src="https://github.com/user-attachments/assets/2b1aeaf9-22ba-4ae6-bc63-771805b8c2b9" /> <!-- Please describe your change, mention any related tickets, and so on here. --> # API and ABI breaking changes <!-- If this is an API or ABI breaking change, please apply the corresponding GitHub label. --> # Expected complexity level and risk <!-- How complicated do you think these changes are? Grade on a scale from 1 to 5, where 1 is a trivial change, and 5 is a deep-reaching and complex change. This complexity rating applies not only to the complexity apparent in the diff, but also to its interactions with existing and future code. If you answered more than a 2, explain what is complex about the PR, and what other components it interacts with in potentially concerning ways. --> # Testing <!-- Describe any testing you've done, and any testing you'd like your reviewers to do, so that you're confident that all the changes work as expected! --> - [ ] <!-- maybe a test you want to do --> - [ ] <!-- maybe a test you want a reviewer to do, so they can check it off when they're satisfied. --> --------- Co-authored-by: = <cloutiertyler@gmail.com>
1 parent b0f3f8d commit aca374a

25 files changed

Lines changed: 696 additions & 70 deletions
Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Browser Quickstart
3+
sidebar_label: Browser
4+
slug: /quickstarts/browser
5+
hide_table_of_contents: true
6+
pagination_next: intro/quickstarts/typescript
7+
---
8+
9+
import { InstallCardLink } from "@site/src/components/InstallCardLink";
10+
import { StepByStep, Step, StepText, StepCode } from "@site/src/components/Steps";
11+
12+
Get a SpacetimeDB app running in the browser with inline JavaScript.
13+
14+
## Prerequisites
15+
16+
- [Node.js](https://nodejs.org/) 18+ installed
17+
- [SpacetimeDB CLI](https://spacetimedb.com/install) installed
18+
19+
<InstallCardLink />
20+
21+
---
22+
23+
<StepByStep>
24+
<Step title="Create your project">
25+
<StepText>
26+
Run the `spacetime dev` command to create a new project with a TypeScript SpacetimeDB module.
27+
28+
This will start the local SpacetimeDB server, publish your module, and generate TypeScript client bindings.
29+
</StepText>
30+
<StepCode>
31+
```bash
32+
spacetime dev --template browser-ts my-spacetime-app
33+
```
34+
</StepCode>
35+
</Step>
36+
37+
<Step title="Build the client bindings">
38+
<StepText>
39+
The generated TypeScript bindings need to be bundled into a JavaScript file that can be loaded in the browser via a script tag.
40+
</StepText>
41+
<StepCode>
42+
```bash
43+
cd my-spacetime-app
44+
npm install
45+
npm run build
46+
```
47+
</StepCode>
48+
</Step>
49+
50+
<Step title="Open in browser">
51+
<StepText>
52+
Open `index.html` directly in your browser. The app connects to SpacetimeDB and displays data in real-time.
53+
54+
The JavaScript code runs inline in a script tag, using the bundled `DbConnection` class.
55+
</StepText>
56+
<StepCode>
57+
```html
58+
<!-- Load the bundled bindings -->
59+
<script src="dist/bindings.iife.js"></script>
60+
61+
<script>
62+
const conn = DbConnection.builder()
63+
.withUri('ws://localhost:3000')
64+
.withModuleName('my-spacetime-app')
65+
.withToken(localStorage.getItem('auth_token'))
66+
.onConnect((conn, identity, token) => {
67+
localStorage.setItem('auth_token', token);
68+
console.log('Connected:', identity.toHexString());
69+
70+
// Subscribe to tables
71+
conn.subscriptionBuilder()
72+
.onApplied(() => {
73+
for (const person of conn.db.person.iter()) {
74+
console.log(person.name);
75+
}
76+
})
77+
.subscribe(['SELECT * FROM person']);
78+
})
79+
.build();
80+
</script>
81+
```
82+
</StepCode>
83+
</Step>
84+
85+
<Step title="Call reducers">
86+
<StepText>
87+
Reducers are functions that modify data — they're the only way to write to the database.
88+
</StepText>
89+
<StepCode>
90+
```javascript
91+
// Call a reducer with named arguments
92+
conn.reducers.add({ name: 'Alice' });
93+
```
94+
</StepCode>
95+
</Step>
96+
97+
<Step title="React to changes">
98+
<StepText>
99+
Register callbacks to update your UI when data changes.
100+
</StepText>
101+
<StepCode>
102+
```javascript
103+
conn.db.person.onInsert((ctx, person) => {
104+
console.log('New person:', person.name);
105+
});
106+
107+
conn.db.person.onDelete((ctx, person) => {
108+
console.log('Removed:', person.name);
109+
});
110+
```
111+
</StepCode>
112+
</Step>
113+
</StepByStep>
114+
115+
## Next steps
116+
117+
- See the [Chat App Tutorial](/tutorials/chat-app) for a complete example
118+
- Read the [TypeScript SDK Reference](/sdks/typescript) for detailed API docs

pnpm-lock.yaml

Lines changed: 19 additions & 70 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

pnpm-workspace.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ packages:
55
- 'templates/react-ts'
66
- 'templates/basic-ts'
77
- 'templates/vue-ts'
8+
- 'templates/browser-ts'
89
- 'templates/svelte-ts'
910
- 'modules/benchmarks-ts'
1011
- 'modules/module-test-ts'
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"description": "Browser web app with TypeScript server",
3+
"client_lang": "typescript",
4+
"server_lang": "typescript"
5+
}

templates/browser-ts/LICENSE

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../licenses/apache2.txt

0 commit comments

Comments
 (0)