Liveblocks 1.5: Foundational API improvements

With Liveblocks 1.5, we’re introducing many foundational improvements to our APIs, making it easier to integrate Liveblocks into your application.

• Disconnecting background WebSocket connections
• Support for multiple room providers
• New APIs for entering and leaving rooms
• Logging out users in single-page applications
• New useOthersListener React hook
• New method for cloning Storage data

Before updating to 1.5, make sure to read our upgrade guide, as there’s a small breaking change in this update.

Disconnecting background WebSocket connections

We’ve added a new option to the Liveblocks client that allows it to disconnect from Liveblocks servers when a WebSocket connection becomes inactive in an unfocused browser window or background tab. This option is called backgroundKeepAliveTimeout.

import { createClient } from "@liveblocks/client";
const client = createClient({  authEndpoint: "/api/liveblocks-auth",  backgroundKeepAliveTimeout: 30000,});

In the example above, the WebSocket connection will automatically disconnect after 30 seconds in an unfocused browser window. As soon as the page regains active focus, the client will restore an active connection, re-synchronize all changes, and resume receiving realtime updates. All within the blink of an eye.

If you’re building a collaborative SaaS product, we highly recommend using this option with a timeout value set to anywhere between 15 and 60 seconds as it may prevent you from hitting simultaneous connections limits.

Support for multiple room providers

For some applications, it’s helpful to connect to multiple Liveblocks rooms from different parts of your React component tree. This was not possible in previous versions of Liveblocks, but it’s now supported in 1.5—you can add an unlimited number of room providers to one application, and the connection will only be closed once the last instance is no longer in use.

In particular, this will be helpful for users of our Zustand and Redux packages, as they can now use our React package, and Comments (private beta), in the same app.

New APIs for entering and leaving rooms

If you aren’t using the @liveblocks/react package directly, you’re most likely entering and leaving to Liveblocks rooms via the @liveblocks/client methods as shown below.

const room = client.enter("my-room", options);
// Then later, when unmountingclient.leave("my-room");

The code above still works in 1.5, but we’re recommending our new approach from this point forwards.

const { room, leave } = client.enter("my-room", options);
// Then later, when unmountingleave();

This pattern allows the client to perform reference counting more reliably, making sure to keep the server connection alive until the last instance no longer needs the room.

If you’re using @liveblocks/zustand or @liveblocks/redux, there will also be a small breaking change when upgrading, as leaveRoom no longer takes the roomId as an argument.

In Zustand:

const {  liveblocks: { leaveRoom },} = useStore();
// ❌ BeforeleaveRoom("roomId");
// ✅ AfterleaveRoom();

In Redux:

const {  liveblocks: { leaveRoom },} = useStore();
// ❌ BeforeleaveRoom("roomId");
// ✅ AfterleaveRoom();

Logging out users in single-page applications

Internally, the Liveblocks client uses an authorization cache to reuse tokens that provide access to multiple rooms, without reauthorizing against your backend. This is efficient, but if you’re building a single-page application (SPA) and wish to log out a specific user, these tokens may remain in the client cache. To wipe that cache, we now offer a new client.logout() API to purge any authorization tokens from cache.

// ✅ Simply call this when logging your user out of your SPAclient.logout();

Calling client.logout() in non-SPAs isn’t necessary since the typical page refresh will remove the client from memory.

New useOthersListener React hook

We now offer a new useOthersListener hook in React which allows you to listen for user enter and leave events. This is particularly useful for creating presence-related UI components, for example showing toast notifications when users enter and leave rooms.

function Component() {  useOthersListener(({ type, user, others }) => {    switch (type) {      case "enter":        // `user` has entered the room        break;
      case "leave":        // `user` has left the room        break;
      case "update":        // Presence for `user` was updated        break;
      case "reset":        // Others list was emptied        break;    }  });}

New method for cloning Storage data

At times, it can be useful to clone parts of your Storage, for instance, in a collaborative whiteboard, where you may wish to duplicate shapes on the canvas. This is now possible using the new clone() method available on LiveObject, LiveMap, and LiveList.

const duplicateShape = useMutation(({ storage }, shapeId) => {  const shapes = storage.get("shapes");  const newShape = shapes.get(shapeId).clone();  shapes.set(randomId(), newShape);}, []);

Upgrade now

Remember to read our upgrade guide before updating, as there’s a small breaking change in this update.

Contributors

Huge thanks to everyone who contributed and specifically to Nimesh Nayaju, Jonathan Rowny and Guillaume Salles for the feedback and help in shaping the new enter and leave API, as well as making React changes backward compatible. Also, big shout out to Chris Nicholas who suggested ideas for the new APIs, and to our incredible community that keeps jumping in to help us improve our infrastructure! Keep checking out the changelog for the full release notes–see you next time!