Skip to content

Commit 7454329

Browse files
bradleyshepbradleyshep
authored
Template README + template.json generation tool (#4570)
# Description of Changes Adds `tools/templates/` scripts to derive template metadata from manifests and generate READMEs from quickstart docs. Replaces slug-based `builtWith` with manifest-derived data and hardcoded quickstart mappings with discovery from docs. **Manifest-based `builtWith`** (`update-template-jsons.ts`) - Reads `package.json`, `Cargo.toml`, and `.csproj` to populate `builtWith` in `.template.json`. - Scoped npm packages normalize to scope (`@angular/core` → `angular`). Excludes `@types/*`. Adds `nodejs` only for nodejs-ts when `@types/node` is present. - Root manifests processed before subdirs; primary framework first (e.g. `react` before `spacetimedb` in react-ts). Dependencies reordered in package.json where needed. **Dynamic quickstart discovery** (`generate-template-readmes.ts`) - Discovers template → quickstart by parsing `--template X` from files in `docs/docs/00100-intro/00200-quickstarts/`. - Optional `quickstart` override in `.template.json`; must resolve under quickstarts dir. - chat-react-ts has no quickstart; uses manual README. **New:** `tools/templates/` (update-template-jsons.ts, generate-template-readmes.ts, README, package.json, pnpm-lock). **Modified:** all `templates/*/.template.json` (added `builtWith`), new/generated `templates/*/README.md`. # API and ABI breaking changes None. # Expected complexity level and risk **1** – Dev tooling only. No runtime or API changes. Scripts are isolated; failures only affect generated metadata and READMEs. # Testing - [ ] `cd tools/templates && pnpm run generate` completes without errors - [ ] Spot-check `builtWith` and generated READMEs for a few templates
1 parent 31b9af3 commit 7454329

39 files changed

Lines changed: 3130 additions & 31 deletions

‎templates/angular-ts/.template.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,12 @@
22
"description": "Angular web app with TypeScript server",
33
"client_framework": "Angular",
44
"client_lang": "typescript",
5-
"server_lang": "typescript"
5+
"server_lang": "typescript",
6+
"builtWith": [
7+
"angular",
8+
"rxjs",
9+
"tslib",
10+
"typescript",
11+
"spacetimedb"
12+
]
613
}

‎templates/angular-ts/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
Get a SpacetimeDB Angular app running in under 5 minutes.
2+
3+
## Prerequisites
4+
5+
- [Node.js](https://nodejs.org/) 18+ installed
6+
- [SpacetimeDB CLI](https://spacetimedb.com/install) installed
7+
8+
Install the [SpacetimeDB CLI](https://spacetimedb.com/install) before continuing.
9+
10+
---
11+
12+
## Create your project
13+
14+
Run the `spacetime dev` command to create a new project with a SpacetimeDB module and Angular client.
15+
16+
This will start the local SpacetimeDB server, publish your module, generate TypeScript bindings, and start the Angular development server.
17+
18+
```bash
19+
spacetime dev --template angular-ts
20+
```
21+
22+
23+
24+
## Open your app
25+
26+
Navigate to [http://localhost:4200](http://localhost:4200) to see your app running.
27+
28+
The template includes a basic Angular app connected to SpacetimeDB.
29+
30+
31+
32+
## Explore the project structure
33+
34+
Your project contains both server and client code.
35+
36+
Edit `spacetimedb/src/index.ts` to add tables and reducers. Edit `src/app/app.component.ts` to build your UI.
37+
38+
```
39+
my-spacetime-app/
40+
├── spacetimedb/ # Your SpacetimeDB module
41+
│ └── src/
42+
│ └── index.ts # Server-side logic
43+
├── src/ # Angular frontend
44+
│ └── app/
45+
│ ├── app.component.ts
46+
│ ├── app.config.ts
47+
│ └── module_bindings/ # Auto-generated types
48+
├── angular.json
49+
└── package.json
50+
```
51+
52+
53+
54+
## Understand tables and reducers
55+
56+
Open `spacetimedb/src/index.ts` to see the module code. The template includes a `person` table and two reducers: `add` to insert a person, and `sayHello` to greet everyone.
57+
58+
Tables store your data. Reducers are functions that modify data — they're the only way to write to the database.
59+
60+
```typescript
61+
import { schema, table, t } from 'spacetimedb/server';
62+
63+
const spacetimedb = schema({
64+
person: table(
65+
{ public: true },
66+
{
67+
name: t.string(),
68+
}
69+
),
70+
});
71+
export default spacetimedb;
72+
73+
export const add = spacetimedb.reducer(
74+
{ name: t.string() },
75+
(ctx, { name }) => {
76+
ctx.db.person.insert({ name });
77+
}
78+
);
79+
80+
export const sayHello = spacetimedb.reducer(ctx => {
81+
for (const person of ctx.db.person.iter()) {
82+
console.info(`Hello, ${person.name}!`);
83+
}
84+
console.info('Hello, World!');
85+
});
86+
```
87+
88+
89+
90+
## Test with the CLI
91+
92+
Open a new terminal and navigate to your project directory. Then use the SpacetimeDB CLI to call reducers and query your data directly.
93+
94+
```bash
95+
cd my-spacetime-app
96+
97+
# Call the add reducer to insert a person
98+
spacetime call add Alice
99+
100+
# Query the person table
101+
spacetime sql "SELECT * FROM person"
102+
name
103+
---------
104+
"Alice"
105+
106+
# Call sayHello to greet everyone
107+
spacetime call say_hello
108+
109+
# View the module logs
110+
spacetime logs
111+
2025-01-13T12:00:00.000000Z INFO: Hello, Alice!
112+
2025-01-13T12:00:00.000000Z INFO: Hello, World!
113+
```
114+
115+
## Next steps
116+
117+
- Read the [TypeScript SDK Reference](https://spacetimedb.com/docs/intro/core-concepts/clients/typescript-reference) for detailed API docs

‎templates/basic-cpp/.template.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
{
22
"description": "A basic C++ server template with only stubs for code",
33
"server_lang": "cpp",
4-
"client_lang": "rust"
4+
"client_lang": "rust",
5+
"builtWith": [
6+
"spacetimedb-sdk"
7+
]
58
}

‎templates/basic-cpp/README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
Get a SpacetimeDB C++ app running in under 5 minutes.
2+
3+
## Prerequisites
4+
5+
- [SpacetimeDB CLI](https://spacetimedb.com/install) installed
6+
- [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html) 4.0.21+ installed
7+
- CMake 3.20+ and a make/ninja backend
8+
- C++20 toolchain (host) — build targets WASM via Emscripten
9+
10+
After installing the SDK, run the appropriate `emsdk_env` script (PowerShell or Bash) so `emcc` and the CMake toolchain file are available on `PATH`.
11+
12+
Install the [SpacetimeDB CLI](https://spacetimedb.com/install) before continuing.
13+
14+
---
15+
16+
## Install Emscripten
17+
18+
Use the official SDK (see [Emscripten downloads](https://emscripten.org/docs/getting_started/downloads.html)) and activate the environment so `emcc` and the CMake toolchain file are on PATH. We recommend Emscripten 4.0.21+.
19+
20+
```bash
21+
# From your emsdk directory (after downloading/cloning)
22+
# Windows PowerShell
23+
./emsdk install 4.0.21
24+
./emsdk activate 4.0.21
25+
./emsdk_env.ps1
26+
27+
# macOS/Linux
28+
./emsdk install 4.0.21
29+
./emsdk activate 4.0.21
30+
source ./emsdk_env.sh
31+
```
32+
33+
34+
35+
## Create your project
36+
37+
Use the CLI-managed workflow with `spacetime build`, which wraps CMake + `emcc` for you, starts the local server, builds/publishes your module, and generates client bindings.
38+
39+
```bash
40+
spacetime dev --template basic-cpp
41+
```
42+
43+
44+
Need manual control? You can still drive CMake+emcc directly (see `spacetimedb/CMakeLists.txt`), but the recommended path is `spacetime build`/`spacetime dev`.
45+
46+
47+
48+
49+
50+
Server code lives in the `spacetimedb` folder; the template uses CMake and the SpacetimeDB C++ SDK.
51+
52+
53+
```
54+
my-spacetime-app/
55+
├── spacetimedb/ # Your C++ module
56+
│ ├── CMakeLists.txt
57+
│ └── src/
58+
│ └── lib.cpp # Server-side logic
59+
├── Cargo.toml
60+
└── src/
61+
└── main.rs # Rust client application
62+
```
63+
64+
65+
66+
## Understand tables and reducers
67+
68+
The template includes a `Person` table and two reducers: `add` to insert, `say_hello` to iterate and log.
69+
70+
```cpp
71+
#include "spacetimedb.h"
72+
using namespace SpacetimeDB;
73+
74+
struct Person { std::string name; };
75+
SPACETIMEDB_STRUCT(Person, name)
76+
SPACETIMEDB_TABLE(Person, person, Public)
77+
78+
SPACETIMEDB_REDUCER(add, ReducerContext ctx, std::string name) {
79+
ctx.db[person].insert(Person{name});
80+
return Ok();
81+
}
82+
83+
SPACETIMEDB_REDUCER(say_hello, ReducerContext ctx) {
84+
for (const auto& person : ctx.db[person]) {
85+
LOG_INFO("Hello, " + person.name + "!");
86+
}
87+
LOG_INFO("Hello, World!");
88+
return Ok();
89+
}
90+
```
91+
92+
93+
94+
## Test with the CLI
95+
96+
Open a new terminal and navigate to your project directory. Then call reducers and inspect data right from the CLI.
97+
98+
```bash
99+
cd my-spacetime-app
100+
101+
# Insert a person
102+
spacetime call add Alice
103+
104+
# Query the person table
105+
spacetime sql "SELECT * FROM person"
106+
107+
# Call say_hello to greet everyone
108+
spacetime call say_hello
109+
110+
# View the module logs
111+
spacetime logs
112+
```
113+
114+
## Notes
115+
116+
- To use a local SDK clone instead of the fetched archive, set `SPACETIMEDB_CPP_SDK_DIR` before running `spacetime dev`/`spacetime build`.
117+
- The template builds to WebAssembly with exceptions disabled (`-fno-exceptions`).
118+
- If `emcc` is not found, re-run the appropriate `emsdk_env` script to populate environment variables.

‎templates/basic-cs/.template.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
{
22
"description": "A basic C# client and server template with only stubs for code",
33
"client_lang": "csharp",
4-
"server_lang": "csharp"
4+
"server_lang": "csharp",
5+
"builtWith": [
6+
"SpacetimeDB.ClientSDK",
7+
"SpacetimeDB.Runtime"
8+
]
59
}

‎templates/basic-cs/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
Get a SpacetimeDB C# app running in under 5 minutes.
2+
3+
## Prerequisites
4+
5+
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) installed
6+
- [SpacetimeDB CLI](https://spacetimedb.com/install) installed
7+
8+
Install the [SpacetimeDB CLI](https://spacetimedb.com/install) before continuing.
9+
10+
---
11+
12+
## Install .NET WASI workload
13+
14+
SpacetimeDB C# modules compile to WebAssembly using the WASI experimental workload.
15+
16+
```bash
17+
dotnet workload install wasi-experimental
18+
```
19+
20+
21+
22+
## Create your project
23+
24+
Run the `spacetime dev` command to create a new project with a C# SpacetimeDB module.
25+
26+
This will start the local SpacetimeDB server, compile and publish your module, and generate C# client bindings.
27+
28+
```bash
29+
spacetime dev --template basic-cs
30+
```
31+
32+
33+
34+
## Explore the project structure
35+
36+
Your project contains both server and client code.
37+
38+
Edit `spacetimedb/Lib.cs` to add tables and reducers. Use the generated bindings in the client project.
39+
40+
```
41+
my-spacetime-app/
42+
├── spacetimedb/ # Your SpacetimeDB module
43+
│ ├── StdbModule.csproj
44+
│ └── Lib.cs # Server-side logic
45+
├── client.csproj
46+
├── Program.cs # Client application
47+
└── module_bindings/ # Auto-generated types
48+
```
49+
50+
51+
52+
## Understand tables and reducers
53+
54+
Open `spacetimedb/Lib.cs` to see the module code. The template includes a `Person` table and two reducers: `Add` to insert a person, and `SayHello` to greet everyone.
55+
56+
Tables store your data. Reducers are functions that modify data — they're the only way to write to the database.
57+
58+
```csharp
59+
using SpacetimeDB;
60+
61+
public static partial class Module
62+
{
63+
[SpacetimeDB.Table(Accessor = "Person", Public = true)]
64+
public partial struct Person
65+
{
66+
public string Name;
67+
}
68+
69+
[SpacetimeDB.Reducer]
70+
public static void Add(ReducerContext ctx, string name)
71+
{
72+
ctx.Db.Person.Insert(new Person { Name = name });
73+
}
74+
75+
[SpacetimeDB.Reducer]
76+
public static void SayHello(ReducerContext ctx)
77+
{
78+
foreach (var person in ctx.Db.Person.Iter())
79+
{
80+
Log.Info($"Hello, {person.Name}!");
81+
}
82+
Log.Info("Hello, World!");
83+
}
84+
}
85+
```
86+
87+
88+
89+
## Test with the CLI
90+
91+
Open a new terminal and navigate to your project directory. Then use the SpacetimeDB CLI to call reducers and query your data directly.
92+
93+
```bash
94+
cd my-spacetime-app
95+
96+
# Call the add reducer to insert a person
97+
spacetime call add Alice
98+
99+
# Query the person table
100+
spacetime sql "SELECT * FROM Person"
101+
name
102+
---------
103+
"Alice"
104+
105+
# Call say_hello to greet everyone
106+
spacetime call say_hello
107+
108+
# View the module logs
109+
spacetime logs
110+
2025-01-13T12:00:00.000000Z INFO: Hello, Alice!
111+
2025-01-13T12:00:00.000000Z INFO: Hello, World!
112+
```
113+
114+
## Next steps
115+
116+
- See the [Chat App Tutorial](https://spacetimedb.com/docs/intro/tutorials/chat-app) for a complete example
117+
- Read the [C# SDK Reference](https://spacetimedb.com/docs/intro/core-concepts/clients/csharp-reference) for detailed API docs

0 commit comments

Comments
 (0)