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](#background-connections)
- [Support for multiple room providers](#multiple-room-providers)
- [New APIs for entering and leaving rooms](#enter-leave-apis)
- [Logging out users in single-page applications](#logging-out-users-in-spas)
- [New useOthersListener React hook](#useOthersListener-react-hook)
- [New method for cloning Storage data](#cloning-storage-data)

Before updating to 1.5, make sure to
[read our upgrade guide](/docs/platform/upgrading/1.5), as there’s a small
breaking change in this update.

## Disconnecting background WebSocket connections [#background-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`.

```ts highlight="5"
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 [#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](/comments) (private beta),
in the same app.

## New APIs for entering and leaving rooms [#enter-leave-apis]

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.

```ts
const room = client.enter("my-room", options);

// Then later, when unmounting
client.leave("my-room");
```

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

```ts
const { room, leave } = client.enter("my-room", options);

// Then later, when unmounting
leave();
```

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:

```ts
const {
  liveblocks: { leaveRoom },
} = useStore();

// ❌ Before
leaveRoom("roomId");

// ✅ After
leaveRoom();
```

In Redux:

```ts
const {
  liveblocks: { leaveRoom },
} = useStore();

// ❌ Before
leaveRoom("roomId");

// ✅ After
leaveRoom();
```

## Logging out users in single-page applications [#logging-out-users-in-spas]

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](/docs/api-reference/liveblocks-client#Client.logout) to
purge any authorization tokens from cache.

```ts
// ✅ Simply call this when logging your user out of your SPA
client.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 [#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.

```ts
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 [#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`.

```tsx highlight="3"
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](/docs/platform/upgrading/1.5) before
updating, as there’s a small breaking change in this update.

## Contributors

Huge thanks to everyone who contributed and specifically to
[Nimesh Nayaju](https://twitter.com/nayajunimesh),
[Jonathan Rowny](https://twitter.com/Jrowny) and
[Guillaume Salles](https://twitter.com/guillaume_slls) 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](https://twitter.com/ctnicholasdev) 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](https://github.com/liveblocks/liveblocks/blob/main/CHANGELOG.md) for
the full release notes–see you next time!