Tools - Dev server

The Liveblocks dev server is a local server that lets you develop and test multiplayer features without connecting to Liveblocks production servers. It is built on our open-source @liveblocks/server package internally.

Features

The dev server fully supports all Multiplayer features, and partially supports other APIs. Learn more.

¹ Excluding features related to Comments and Notifications.
² Basic room APIs are partially supported, but room permissions and metadata are not fully implemented yet.
³ Basic APIs will return dummy data, so you can still use the Liveblocks dev server to test other features in your app.

Set up the dev server

The development server currently only supports connecting with public key or access token authentication. ID token authentication will be supported in future.

1. Install Bun

   The Liveblocks dev server requires Bun to be installed.

   Terminal

   npm install -g bun

2. Run the dev server

   Start the dev server from your project directory—it runs on http://localhost:1153.

   Terminal

   npx liveblocks dev

3. Connect to the dev server

   Point your client and auth endpoint to the dev server. The easiest way to do this is run the dev server and press p. It copies a prompt you can paste into your AI code editor, which will intelligently make the changes for you.

   If you don’t use the prompt, you can manually add baseUrl and change your secret key:

   import { LiveblocksProvider } from "@liveblocks/react";
   function App() {  return (    <LiveblocksProvider      baseUrl="http://localhost:1153"      authEndpoint="/api/liveblocks-auth"    >      {/* Your app */}    </LiveblocksProvider>  );}

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  baseUrl: "http://localhost:1153",  secret: "sk_localdev",});

   Alternate snippet for public key

4. Complete

   You're all set up, open your app and start building collaborative features using the local dev server, or set up CI testing with your application.

Partially supported features

A number of unsupported features are partially implemented so you can run your app without seeing errors. For example, useThreads is not supported yet, but it will always return an empty array so you can still view your application.

// ✅ Fully supportedconst others = useOthers();const shapes = useStorage((root) => root.shapes);
// ⚠️ Returns dummy data such as empty arraysconst { threads } = useThreads();const { inboxNotifications } = useInboxNotifications();
// ⚠️ Nothing happens when calling unsupported functionsconst createNewThread = useCreateThread();createNewThread({ body: {}, attachments: [] });

// ✅ Fully supportedconst storage = await liveblocks.getStorageDocument("my-room-id");await liveblocks.broadcastEvent("my-room-id", { type: "REFRESH" });
// ⚠️ Room APIs are supported but permissions and metadata are ignoredawait liveblocks.createRoom("my-new-room-id", {  defaultAccesses: ["room:write"],  metadata: { title: "My title" },});// { metadata: {}, defaultAccesses: [], ... }await liveblocks.getRoom("my-new-room-id");
// ⚠️ Returns dummy data such as empty arraysconst { data: threads } = await liveblocks.getThreads({  roomId: "my-room-id",});
// ⚠️ Nothing happens when calling unsupported functionsawait liveblocks.createThread({  roomId: "my-room-id",  body: {},});

In future, we plan to support more features in the dev server.

REST API

The REST API supports the same set of features as the Node.js package. To use it, point your requests to the dev server URL and use sk_localdev as the secret key.

$curl http://localhost:1153/v2/* \  -H 'Authorization: Bearer sk_localdev'

Continuous Integration (CI) testing

You can use the dev server in CI environments by setting up a test environment file and running the dev server as a service container. Learn more in our guide on how to set up Continuous Integration (CI) testing.

Docker

You can run the dev server as a Docker container, which is useful for CI environments where you may not have Bun installed.

$docker run -p 1153:1153 ghcr.io/liveblocks/cli dev

To persist data between container restarts, mount a volume:

$docker run -p 1153:1153 -v liveblocks-data:/app/.liveblocks ghcr.io/liveblocks/cli dev

Source code

The source code is available in our GitHub repository.

Examples

The following examples fully support the dev server.

• 

  Collaborative To-do List

  Next.jsVueSvelteKitSolid.jsJavaScript
• 

  Live Avatar Stack

  Next.jsNuxt.jsVueSvelteKitSolid.js
• 

  Collaborative SpreadsheetAdvanced

  Next.js
• 

  Collaborative WhiteboardAdvanced

  Next.js