ReactZustandStorageTutorials

How to use Liveblocks Storage with Zustand

In this guide, we’ll be learning how to use Liveblocks Storage with Zustand using the APIs from the [@liveblocks/zustand][] package.

Sync and persist the state across client

As opposed to presence, some collaborative features require that every user interacts with the same piece of state. For example, in Google Docs, it is the paragraphs, headings, images in the document. In Figma, it’s all the shapes that make your design. That’s what we call the room’s “storage”.

The room’s storage is a conflicts-free state that multiple users can edit at the same time. It is persisted to our backend even after everyone leaves the room. Liveblocks provides custom data structures inspired by CRDTs that can be nested to create the state that you want.

  • LiveObject - Similar to JavaScript object. If multiple users update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
  • LiveList - An ordered collection of items synchronized across clients. Even if multiple users add/remove/move elements simultaneously, LiveList will solve the conflicts to ensure everyone sees the same collection of items.
  • LiveMap - Similar to a JavaScript Map. If multiple users update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.

When using our Zustand integration you cannot interact directly with these data structures. Our middleware synchronizes your store with our data structures based on the storageMapping configuration.

Here is an example to explain how it works under the hood. Imagine you have the following store:

src/store.ts
/* ...client setup */
const useStore = create<WithLiveblocks<State>>()(  liveblocks(    (set) => ({      firstName: "Marie",      lastName: "Curie",      discoveries: ["Polonium", "Radium"],
      setFirstName: (firstName) => set({ firstName }),      setLastName: (lastName) => set({ lastName }),      addDiscovery: (discovery) =>        set((state) => ({          discoveries: state.discoveries.concat([discovery]),        })),    }),    {      client,      storageMapping: {        firstName: true,        lastName: true,        discoveries: true,      },    }  ));

With this setup, the room's storage root is:

const root = new LiveObject({  firstName: "Marie",  lastName: "Curie",  discoveries: new LiveList(["Polonium", "Radium"]),});

If you update your store by calling setFirstName("Pierre"), the middleware will do root.set("firstName", "Pierre") for you and update the store of all the users currently connected to the room. The middleware compares the previous state and the new state to detect changes and patch our data structures accordingly.

The reverse process happens when receiving updates from other clients; the middleware patches your immutable state.

When entering a room with liveblocks.enterRoom, the middleware fetches the room's storage from our server and patches your store. If this is the first time you're entering a room, the storage will be initialized with the current value in your Zustand state, typically your initial state.

Related guides