Getting Started

This guide walks through a minimal full-stack React project in Room Service. If you're looking for a more detailed overview of the React client, checkout this doc.

Room Service is (unsurprisingly) built around rooms! Rooms are a bit like folders: they contain other things. If you change something in a room, it will get sent to anyone else listening to that thing in that room.

Inside of rooms you'll find a data-structures that render optimistically, resolve conflicts on their own, and update in real-time.

Maps, Lists, and Presence

Room Service Maps are simple key-value stores with last-writer-wins resolution.

import { useMap } from "@roomservice/react";

const [cafe, map] = useMap("myRoom", "myMap");

map?.set("name", "Java Beach Cafe");; // "Java Beach Cafe"

Room Service Lists are like a regular list, but they prevent race conditions, prevent interweaving, and preserve user intent when multiple people edit them at the same time. Dive into the details here.

import { useList } from "@roomservice/react";

const [todos, list] = useList("myRoom", "myList");

list?.insertAt(0, "water plants").push("feed dogs", "buy ginger");

todos[0]; // "Water Plants"


Room Service uses short-lived session tokens that you generate on the server, and then pass back to the browser. If you want allow a user to do something in Room Service, you need to create a new token for them. Tokens last for 6 hours and each token is associated with permissions that the user is allowed to do during that session.

Diagram showing your Backend asks Room Service to create a token for a user.

In order for the browser clients to open a connection to Room Service, you'll need to give it this token.

Diagram showing your backend giving your browser the token

A Fullstack Example

To follow along, use this script to generate a project for you:

# npm
npx create-next-app --example --example-path next.js-todolist

# yarn
yarn create next-app --example --example-path next.js-todolist

Then install the dependencies and start the project:

npm install;
npm run dev;

# Or ...

yarn dev;

Finally, add your API Key to a .env file, which you can get here.


Room Service uses short-lived session tokens. Before a user connects to a room, we need to generate a token for them on the server that's associated with some resources. In this case, it's full access to the room.

On the browser, we'll create a function to call the API endpoint. We'll pass in what room this user is trying to access. If our API route succeeds, we'll return the resulting information.

At the root of the project, we'll pass this function into the RoomServiceProvider. When the user tries to connect to the room, Room Service will call this function to check if they're allowed to do that.

Then, you're free to call Room Service hooks from anywhere in your project. We'll create a new map to store values for a couple inputs.

The first value is a regular JavaScript object, is an instance of a Map class that you can use to modify the object.

const [object, map] = useMap("myroom", "mymap");

When a user user calls map.set(), Room Service will send the changes to every other client that's connected to this room.

Try this out by opening up this example in two browser windows!

Made with 🌁 in San Francisco

About Us

Copyright @ 2021

Room Service