Add to existing product
Adding multiplayer with Room Service involves two steps:
- (10 minutes) Create an Auth Webhook: a POST-request-accepting HTTP endpoint on your server.
- (5 minutes) Install the browser SDK and start building!
Creating an Auth Webhook
Room Service uses your auth setup. To do that, we ask you to create an endpoint that accepts POST requests on your server.
By default, this endpoint receives a POST body from the browser SDK containing resources the user would like to access. To authorize the user, we'll forward the message along with our API key and a user id to Room Service via the
The following is an example in Node.js/Express, but you can build your route in any language:
Setting up the browser SDK
Room Service comes with a ~4kb browser library written in TypeScript. Install it with:
To start, import the SDK and create a new client that points to your Auth Webhook.
Creating your first room
The key concept of Room Service is the "room". Rooms are like shared folders that hold all your maps, lists, and presence keys inside. If you update something within a room, everyone who's connected to the room will receive the update.
You might create a room for a team, a document, a page, or anything else you'd like.
Working with lists
Room Service comes with several data structures that make updates locally-first, so your app is as fast as possible. Each data structure manages conflicts between users automatically, but this is most obvious in lists.
To create a list, grab one from the room:
Lists (and maps) are immutable, so every change returns a new copy of the list:
Anytime you make a change to something in Room Service, we'll automatically tell everyone else connected to the room. To get updates, we just have to subscribe to them.
To get data out of the list, we can either convert the whole thing (fast) or get an item directly (faster):
And when you need to, you can delete anything from the list:
Conflicts are managed automatically
Say Alice deletes the 2nd item in a list, at the same time Bob updates the 3rd item. What happens?
In a normal array, this is undefined behavior. If Alice's network is just a bit faster and she goes first, then Bob is changing
"horses", which he probably didn't want to do.
In Room Service, this just-works™ the way you'd want it to. Regardless of who's arrives first:
- Bob will change
- Alice will delete
This works because Room Service's maps and lists aren't true objects and arrays. They're distributed data structures (CRDT-likes) meant for building multiplayer, with similar interfaces.
Working with maps
Much like lists, Room Service also comes with optimistically updating maps. To create one, just use the room:
Like lists, maps are immutable; their update functions return a copy of themselves.
To get updates on maps, just subscribe to them with the room.
To get data out of the map, use