# Description of Changes
- Node.js: Use esbuild instead of tsx
- Node.js: Remove interactive CLI since it doesn't work with `spacetime
dev`
- Next.js: Fix onError callback to use single argument (ctx) and use
ctx.event for the error.
- Next.js: Replace lint-disable comment with `_connection` for the
unused variable.
- Updated quickstart docs to use proper `withDatabaseName`
# API and ABI breaking changes
None.
# Expected complexity level and risk
**Complexity: 1–2.** Small tooling, type, and lint tweaks. Low risk.
# Testing
- [ ] Build affected templates (e.g. `pnpm build` in nextjs-ts).
- [ ] Lint passes.
# Description of Changes
This PR implements support for the `spacetime.json` configuration file
that can be used to set up common `generate` and `publish` targets. An
example of `spacetime.json` could look like this:
```
{
"dev_run": "pnpm dev",
"generate": [
{ "out-dir": "./foobar", "module-path": "region-module", "language": "c-sharp" },
{ "out-dir": "./global", "module-path": "global-module", "language": "c-sharp" },
],
"publish": {
"database": "bitcraft",
"module-path": "spacetimedb",
"server": "local",
"children": [
{ "database": "region-1", "module-path": "region-module", server: "local" },
{ "database": "region-2", "module-path": "region-module", server: "local" }
]
}
}
```
With this config, running `spacetime generate` without any arguments
would generate bindings for two targets: `region-module` and
`global-module`. `spacetime publish` without any arguments would publish
three modules, starting from the parent: `bitcraft`, `region-1`, and
`region-2`. On top of that, the command `pnpm dev` would be executed
when using `spacetime dev`.
It is also possible to pass additional command line arguments when
calling the `publish` and `generate` commands, but there are certain
limitations. There is a special case when passing either a module path
to generate or a module name to publish. Doing that will filter out
entries in the config file that do not match. For example, running:
```
spacetime generate --project-path global-module
```
would only generate bindings for the second entry in the `generate`
list.
In a similar fashion, running:
```
spacetime publish region-1
```
would only publish the child database with the name `region-1`
Passing other existing arguments is also possible, but not all of the
arguments are available for multiple configs. For example, when running
`spacetime publish --server maincloud`, the publish command would be
applied to all of the modules listed in the config file, but the
`server` value from the command line arguments would take precedence.
Running with arguments like `--bin-path` would, however, would throw an
error as `--bin-path` makes sense only in a context of a specific
module, thus this wouldn't work: `spacetime publish --bin-path
spacetimedb/target/debug/bitcraft.wasm`. I will throw an error unless
there is only one entry to process, thus `spacetime publish --bin-path
spacetimedb/target/debug/bitcraft.wasm bitcraft` would work, as it
filters the publish targets to one entry.
# API and ABI breaking changes
None
# Expected complexity level and risk
3
The config file in itself is not overly complex, but when coupled with
the CLI it is somewhat tricky to get right. There are also some changes
that I had to make to how clap arguments are validated - because the
values can now come from both the config file and the clap config, we
can't use some of the built-in validations like `required`, or at least
I haven't found a clean way to do so.
# Testing
I've added some automated tests, but more tests and manual testing is
coming.
---------
Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: bradleyshep <148254416+bradleyshep@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
# Description of Changes
Adds a Node.js quickstart template and documentation for SpacetimeDB.
## Template (`templates/nodejs-ts/`)
- SpacetimeDB module with TypeScript (`spacetimedb/src/index.ts`)
- Node.js client with interactive CLI (`src/main.ts`)
- File-based token persistence (`.spacetimedb-token`) instead of
localStorage
- Table change callbacks (`onInsert`, `onDelete`)
- Graceful shutdown handlers for `SIGINT`/`SIGTERM`
- Pre-generated module bindings in `src/module_bindings/`
## Documentation
(`docs/docs/00100-intro/00200-quickstarts/00300-nodejs.md`)
- Step-by-step quickstart guide following existing pattern
- Covers project creation with `spacetime dev --template nodejs-ts`
- Explains project structure and client code
- Documents interactive CLI commands (`list`, `hello`, `<name>`)
- Covers Node.js-specific considerations (WebSocket support, token
storage)
- Documents environment variable configuration (`SPACETIMEDB_HOST`,
`SPACETIMEDB_DB_NAME`)
## Consistency
- Environment variables follow the same `HOST`/`DB_NAME` naming
convention as other quickstarts
- Documentation structure mirrors React and Next.js quickstarts
# API and ABI breaking changes
None.
# Expected complexity level and risk
1 - Additive change only. New template and documentation, no
modifications to existing functionality.
# Testing
- [ ] Run `spacetime dev --template nodejs-ts` and verify project
initializes
- [ ] Run `npm run dev` and verify connection to SpacetimeDB
- [ ] Test adding a person by typing a name
- [ ] Test `list` command shows all people
- [ ] Test `hello` command calls reducer (check server logs)
- [ ] Verify token persistence works across restarts
- [ ] Test graceful shutdown with Ctrl+C
- [ ] Check documentation renders correctly
bradleyshep