Refactors TypeScript into a single spacetimedb package (#3248)

# Description of Changes

This PR moves most of the contents of `@clockworklabs/spacetimedb-sdk`
into the `spacetimedb` module. The `spacetimedb` module now exports
`sdk` and `server` as separate subpaths where `sdk` contains the code
which was previously in `@clockworklabs/spacetimedb-sdk`.

In particular it makes the following moves:

- `/sdks/typescript/packages/sdk` -> `/sdks/typescript`
- most of the contents of `/sdks/typescript/packages/sdk` ->
`crates/bindings-typescript`
- `/sdks/typescript/packages/test-app` ->
`crates/bindings-typescript/test-app`

The following packags was NOT moved:

`/sdks/typescript/examples/quickstart-chat`

## Motivation

In accordance with
#3250, we would like
to consolidate `@clockworklabs/spacetimedb-sdk` into a single
`spacetimedb` package so that users can import the different things they
need from a single package.

### Pros:
- allow users to install a single package with subpaths `spacetimedb`,
`spacetimedb/react`, `spacetimedb/sdk`, `spacetimedb/server`, etc.
- Is much simpler for bundling, etc.
- Is backwards compatible with `@clockworklabs/spacetimedb-sdk` which
now becomes a thin wrapper
- eventually allow us to break up the `spacetimedb` package into other
packages if we want to split them up (e.g. `@spacetimedb/lib`,
`@spacetimedb/sdk`, etc.) and we can solve the build complexity that
introduces when we get to it
- eventually allow us to move `bindings-csharp` out of the crates
directory where it probably doesn't belong anyway
- organizes all TypeScript packages into the packages directory where
you'd normally expect them, with the possible exception of
`/sdks/typescript` if we wanted to leave that separate

### Cons:
- The `sdk` directory is now a bit of a ruse as to where the code
actually lives since it's just a thin wrapper. If it eventually becomes
its own independent package, we'll also have to break up spacetimedb
into `@spacetimedb/lib` and `@spacetimedb/server` so that
`@clockworklabs/spacetimedb-sdk` can depend on `@spacetimedb/lib` while
being a dependency of `spacetimedb`.

Ideally this change would have been made later, however, it became
necessary for the following **heinously disastrous chain of forcing
moves**:

1. Adding `react` support necessitated shipping react as an optional
peer dependency under `@clockworklabs/spacetimedb-sdk/react`
2. This required adding a new build target/export/bundle
3. Previously `@clockworklabs/spacetimedb-sdk` was configured to have
`noExternal` for `spacetimedb` meaning it would collect the library into
the sdk bundle. I attempted to continue this for react support but...
4. Creating a new `react` bundle which also pulled in `spacetimedb`
caused their to be nominal type conflicts between classes in the
duplicate `spacetimedb` bundles.
5. Changing `spacetimedb` to be included as `external` caused compile
errors because `@clockworklabs/spacetimedb-sdk` is configured in
`tsconfig.json` to fail on unused variables and it was now including the
source of `spacetimedb` which is not configured to error on unused
variables and has "unused" private variables which are actually used by
us secretly, but not exposed to the clients.
> SIDE NOTE: The unused variables settings cannot be turned off on a
line by line basis, so it has to be turned off entirely, but in order to
maintain the linting checks we had I used `eslint` to enforce the rule
so that we could disable it line by line. (This caused me to discover
quite a lot of things that were broken that were caught by `eslint`
being applied to the entire project. `eslint` was previously only
applied to the `quickstart-chat` and the `crates/bindings-typescript`
library)
6. Changing the build to be external, now requires `spacetimedb` to also
be published to npm as its own module which
`@clockworklabs/spacetimedb-sdk` now imports, which requires that we add
`tsup` config to `spacetimedb` to publish a built version of the
library.
7. The only way to avoid that is to move the `sdk` and `react` code from
`@clockworklabs/spacetimedb-sdk` into the existing `spacetimedb` package
to avoid the duplicate import problem on step 4 and change
`@clockworklabs/spacetimedb-sdk` back to again use `noExternal` for its
`spacetimedb` dependency.

And here we are. I chose not to move `/crates/bindings-typescript` even
though that's probably not a great place long term. It would be better
to have it in `/packages/spacetimedb` or `/npm-packages/spacetimedb` or
`/ts-packages/spacetimedb` or something, and move all our TypeScript
packages in there. But that is a different matter.

The net result however is that we have a new `spacetimedb` package which
exports the different parts of the API under:

- `spacetimedb`
- `spacetimedb/server`
- `spacetimedb/sdk`
- `spacetimedb/react`

while still not breaking the existing deploy process, nor any
users/developers who are currently using
`@clockworklabs/spacetimedb-sdk`.

I think long term should we ever decide to split `spacetimedb` up into
multiple packages or if we have additional unrelated packages, we should
publish them to the `@spacetimedb` org which I reserved for us here:

https://www.npmjs.com/org/spacetimedb

> NOTE: `spacetimedb` is a package and `@spacetimedb` is an org.
`spacetimedb/sdk` is not a separate package, it's a subpath export of
the `spacetimedb` package, whereas `@spacetimedb/sdk` would be (and
would need to be) it's own separate package. You can certainly have both
`spacetimedb/sdk` and `@spacetimedb/sdk`. We could for example host the
code for the sdk at `@spacetimedb/sdk` and just reexport it from
`spacetimedb` under the `spacetimedb/sdk` subpath.

# API and ABI breaking changes

This should not change or modify the API or ABI in any way. If it does
so accidentally it is a bug, although I carefully went through the
exports.

# Expected complexity level and risk

3 because it changes how the SDK is built a bit and rearranges a lot of
paths.

# Testing

- [x] All of the CI passes
- [x] I also ran quickstart-chat to confirm that it is not broken
- [x] I also ran test-app

Author: cloutiertyler

.github/workflows/typescript-lint.yml

@@ -25,7 +25,6 @@ jobs:
           run_install: true
 
       - name: Get pnpm store directory
-        working-directory: sdks/typescript
         shell: bash
         run: |
           echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
@@ -39,5 +38,4 @@ jobs:
             ${{ runner.os }}-pnpm-store-
 
       - name: Lint
-        working-directory: sdks/typescript
         run: pnpm lint

.github/workflows/typescript-test.yml

@@ -51,7 +51,7 @@ jobs:
         run: pnpm build
 
       - name: Run SDK tests
-        working-directory: sdks/typescript/packages/sdk
+        working-directory: sdks/typescript
         run: pnpm test
 
       # - name: Extract SpacetimeDB branch name from file

.prettierignore

@@ -3,3 +3,4 @@ pnpm-lock.yaml
 dist
 target
 .github
+coverage

Cargo.toml

@@ -47,7 +47,7 @@ members = [
   "sdks/rust/tests/connect_disconnect_client",
   "tools/upgrade-version",
   "tools/license-check",
-  "sdks/typescript/packages/test-app/server",
+  "crates/bindings-typescript/test-app/server",
 ]
 default-members = ["crates/cli", "crates/standalone", "crates/update"]
 # cargo feature graph resolver. v3 is default in edition2024 but workspace

crates/bindings-typescript/eslint.config.js

@@ -6,20 +6,6 @@
   "bugs": {
     "url": "https://github.com/clockworklabs/SpacetimeDB/issues"
   },
-  "source": "src/index.ts",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "src/index.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "source": "./src/index.ts",
-      "development": "./src/index.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "default": "./dist/index.mjs"
-    }
-  },
   "files": [
     "src",
     "dist",
@@ -33,29 +19,136 @@
   "license": "ISC",
   "author": "Clockwork Labs",
   "type": "module",
+  "sideEffects": false,
   "scripts": {
-    "build": "tsc",
-    "format": "prettier --write .",
-    "lint": "eslint . && prettier . --check",
+    "build": "tsup",
+    "format": "prettier . --write --ignore-path ../../.prettierignore",
+    "lint": "eslint . && prettier . --check --ignore-path ../../.prettierignore",
     "test": "vitest run",
     "coverage": "vitest run --coverage",
-    "generate": "cargo run -p spacetimedb-codegen --example regen-typescript-moduledef && prettier --write src/autogen"
+    "brotli-size": "brotli-size dist/index.js",
+    "size": "pnpm -s build && size-limit",
+    "generate:moduledef": "cargo run -p spacetimedb-codegen --example regen-typescript-moduledef && prettier --write src/lib/autogen",
+    "generate:client-api": "cargo build -p spacetimedb-standalone && cargo run -p spacetimedb-client-api-messages --example get_ws_schema > ws_schema.json && cargo run -p spacetimedb-cli generate --lang typescript --out-dir src/sdk/client_api --module-def ws_schema.json && rm ws_schema.json && find src/sdk/client_api -type f -exec perl -pi -e 's#\\@clockworklabs/spacetimedb-sdk#../../index#g' {} + && prettier --write src/sdk/client_api",
+    "generate:test-app": "pnpm --filter @clockworklabs/test-app generate",
+    "generate": "pnpm generate:moduledef && pnpm generate:client-api && pnpm generate:test-app"
   },
+  "source": "src/index.ts",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "source": "./src/index.ts",
+      "development": "./src/index.ts",
+      "browser": "./dist/index.browser.mjs",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    },
+    "./sdk": {
+      "types": "./src/sdk/index.ts",
+      "browser": "./dist/sdk/index.browser.mjs",
+      "import": "./dist/sdk/index.mjs",
+      "require": "./dist/sdk/index.cjs",
+      "default": "./dist/sdk/index.mjs"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.cjs",
+      "default": "./dist/server/index.mjs"
+    }
+  },
+  "size-limit": [
+    {
+      "name": "cjs (brotli)",
+      "path": "dist/index.cjs",
+      "brotli": true,
+      "limit": "25 kB"
+    },
+    {
+      "name": "esm (brotli)",
+      "path": "dist/index.mjs",
+      "brotli": true,
+      "limit": "20 kB"
+    },
+    {
+      "name": "esm (gzip)",
+      "path": "dist/index.mjs",
+      "gzip": true,
+      "limit": "25 kB"
+    },
+    {
+      "name": "esm (uncompressed)",
+      "path": "dist/index.mjs",
+      "brotli": false,
+      "limit": "150 kB"
+    },
+    {
+      "name": "esm min (brotli)",
+      "path": "dist/min/index.mjs",
+      "brotli": true,
+      "limit": "10 kB"
+    },
+    {
+      "name": "esm min (gzip)",
+      "path": "dist/min/index.mjs",
+      "gzip": true,
+      "limit": "15 kB"
+    },
+    {
+      "name": "esm min (uncompressed)",
+      "path": "dist/min/index.mjs",
+      "brotli": false,
+      "limit": "60 kB"
+    },
+    {
+      "name": "sdk esm min (brotli)",
+      "path": "dist/min/sdk/index.browser.mjs",
+      "brotli": true,
+      "limit": "10 kB"
+    },
+    {
+      "name": "sdk esm min (gzip)",
+      "path": "dist/min/sdk/index.browser.mjs",
+      "gzip": true,
+      "limit": "15 kB"
+    },
+    {
+      "name": "sdk esm min (uncompressed)",
+      "path": "dist/min/sdk/index.browser.mjs",
+      "limit": "10 kB"
+    }
+  ],
   "dependencies": {
-    "@zxing/text-encoding": "^0.9.0",
     "base64-js": "^1.5.1",
     "prettier": "^3.3.3"
   },
+  "peerDependencies": {
+    "undici": "^6.19.2"
+  },
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
+    "@size-limit/file": "^11.2.0",
     "@typescript-eslint/eslint-plugin": "^8.18.2",
     "@typescript-eslint/parser": "^8.18.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "brotli-size-cli": "^1.0.0",
     "eslint": "^9.33.0",
     "globals": "^15.14.0",
+    "size-limit": "^11.2.0",
     "ts-node": "^10.9.2",
+    "tsup": "^8.1.0",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.18.2",
-    "vite": "^7.1.3",
+    "vite": "^7.1.5",
     "vitest": "^3.2.4"
   }
 }

crates/bindings-typescript/package.json

@@ -1,11 +1,12 @@
-export * from './connection_id';
-export * from './algebraic_type';
-export * from './algebraic_value';
-export { default as BinaryReader } from './binary_reader';
-export { default as BinaryWriter } from './binary_writer';
-export * from './schedule_at';
-export * from './time_duration';
-export * from './timestamp';
-export * from './utils';
-export * from './identity';
+export * from './lib/connection_id';
+export * from './lib/algebraic_type';
+export * from './lib/algebraic_value';
+export { default as BinaryReader } from './lib/binary_reader';
+export { default as BinaryWriter } from './lib/binary_writer';
+export * from './lib/schedule_at';
+export * from './lib/time_duration';
+export * from './lib/timestamp';
+export * from './lib/utils';
+export * from './lib/identity';
+export * from './sdk';
 export { default as t } from './server/type_builders';

crates/bindings-typescript/src/index.ts

@@ -14,7 +14,7 @@ import {
   deepEqual as __deepEqual,
   type AlgebraicType as __AlgebraicTypeType,
   type AlgebraicTypeVariants as __AlgebraicTypeVariants,
-} from '../index';
+} from '../../index';
 import { SumType } from './sum_type_type';
 // Mark import as potentially unused
 declare type __keep_SumType = SumType;