Sign in

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.

FeatureSupport
Liveblocks Storage (LiveObject, Presence, Broadcast, etc.)✅
Liveblocks Yjs✅
Text editors (Tiptap, BlockNote, Lexical)✅ ¹
Public key authentication✅
Access token authentication✅
ID token authentication❌
Room Node.js methods⚠️ ²
Room REST APIs⚠️ ²
Comments❌ ³
Notifications❌ ³
AI Agents❌
Other APIs❌

¹ 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",});

  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.

React
// ✅ 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: [] });
Node.js
// ✅ 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'

Quick local testing

When your unit tests need the Liveblocks dev server to be running, you can use --cmd "vitest run" (or whichever test command you use) to run your tests in a temporary, ephemeral, dev server instance.

This mode will:

  1. Start a fresh, empty, dev server instance.
  2. Run your unit tests.
  3. Stop the dev server.

Example output:

Terminal
npx liveblocks dev --cmd 'vitest run'Starting the Liveblocks dev server...
Liveblocks dev server running at http://localhost:1153Server logs: /tmp/liveblocks-dev-XXXXXX/server.log
✓ src/__tests__/your-unit-test.test.ts (28 tests) 40ms
Test Files  1 passed (1)      Tests  28 passed (28)   Start at  11:24:51   Duration  0.5s
Liveblocks dev server shut down

We recommend:

  1. npx liveblocks dev for manual testing and development, which retains data between runs in the .liveblocks/ folder.
  2. npx liveblocks dev --cmd "vitest run" for locally running your unit tests against a fresh instance (your local data in .liveblocks/ won't be affected by your unit tests).

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 how do this in our step-by-step guide.

How to set up Continuous Integration (CI) testing

End-to-End (E2E) testing

You can use the dev server to run end-to-end tests with tools such as Playwright. Learn how to do this in our step-by-step guide.

How to set up End-to-End (E2E) testing with Playwright

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.