Getting Started

Welcome to Room Service!

This guide will walk you through setting up a todo list demo and go over a couple of key concepts to help you learn how to make multiplayer products.

Step One:

First, grab an API key by setting up an account at app.roomservice.dev.

Step Two:

Create a new project by copying this command and pasting it into your terminal:

1# npm
2npx create-next-app --example https://github.com/getroomservice/examples --example-path next.js-todolist
3# yarn
4yarn create next-app --example https://github.com/getroomservice/examples --example-path next.js-todolist

This will create a new project from the next.js-todolist example project.

Then, run yarn install or npm install to install the dependencies.

Step Three:

Create a file named .env in the root of the project, and add your api key to it.

1// .env
2ROOMSERVICE_API_KEY=<YOUR API KEY>

Step Four:

Run yarn dev or npm run dev in your terminal to launch the product!

Open up the browser in two different windows and watch as the list updates in real time using the List data type.

Data Types

Room Service provides a number of different data types which are the building blocks of multiplayer features.

Lists are an ordered collection of items, stored in a CRDT-like data structure. Lists can contain other lists and maps, resolve conflicts automatically, and do their best to preserve user intent while maintaining order.

A Map is a distributed key-value store. Maps can contain other maps or lists, resolve conflicts automatically, and update in real-time. When you update a map, it updates optimistically and forwards the message to everyone else in the room in the background.

With Presence, you can store a temporary string, boolean, number, or JSON object on a user. Use it to build mouse cursors, shared highlighting, draggable effects, or any other feature that doesn't require long-term persistence.

Manipulating Lists

This demo project uses our React library in order to create and manipulate lists (and other data structures).

1// pages/index.js
2
3function onCheckOff(i) {
4  if (!listClient) return;
5  listClient.delete(i);
6}
7
8// listClient.delete(i) returns a new list with index i deleted

View the Lists docs to view the rest of the List operations.

Authorization​

Room Service uses your own authentication/authorization system. The client will send a post request to your server, and you decide if that user is authorized or not.

For example, in our next.js todo demo our server is currently accepting post requests from our client. You can add in authorization by simply wrapping the fetch request in your authorization logic.

1// pages/api/roomservice.js
2
3export default async (req, res) => {
4  const body = req.body;
5  const user = "some-user-" + getRandomInt(1, 200);
6
7  const r = await fetch("https://super.roomservice.dev/provision", {
8    method: "post",
9    headers: {
10      Authorization: `Bearer: ${API_KEY}`,
11      "Content-Type": "application/json",
12    },
13    body: JSON.stringify({
14      user: user,
15      resources: body.resources,
16    }),
17  });
18
19  const json = await r.json();
20  res.json(json);
21};