Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

cloutiertyler
Copy link
Contributor

@cloutiertyler cloutiertyler commented Sep 15, 2025

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)

  1. 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.
  2. 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

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

Copy link
Contributor

@JulienLavocat JulienLavocat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, I really like the syntax!

@cloutiertyler cloutiertyler changed the title Implements React Hooks for the TypeScript SDK Refactors TypeScript into a single spacetimedb package Sep 18, 2025
@cloutiertyler cloutiertyler requested a review from bfops September 18, 2025 21:54
@bfops
Copy link
Collaborator

bfops commented Sep 18, 2025

This seems fine to me, but likely breaks the current deploy process since we only mirror sdks/typescript to the https://github.com/clockworklabs/spacetimedb-typescript-sdk/ repo, and now that directory is not the only thing that's required.

This may have to come hand-in-hand with migrating over the npm+provenance stuff that I've been putting off migrating.

@cloutiertyler
Copy link
Contributor Author

cloutiertyler commented Sep 18, 2025

@bfops Mm, that is a good point, although if we add publishing spacetimedb to the deploy process, then we could again just push/mirror that. I guess we should probably coordinate on how to do this though.

Copy link
Contributor

@JulienLavocat JulienLavocat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was a lot of work! LGTM, I've left one minor comment that you can ignore if you wnat

@JulienLavocat
Copy link
Contributor

@cloutiertyler @bfops I think we should only publish the spacetimedb package and not mirror the old @clockworklabs/typescript-sdk. It's less confusing for users as we can simply say "If you want to upgrade to the newer versions, please use our new spacetimedb/sdk package"

@cloutiertyler cloutiertyler marked this pull request as ready for review September 19, 2025 19:33
@cloutiertyler cloutiertyler added this pull request to the merge queue Sep 19, 2025
Merged via the queue into master with commit c83f55f Sep 19, 2025
38 of 40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants