At Liveblocks, we strive to craft ergonomic and easy-to-use APIs that allow
developers to build performant multiplayer experiences. With 0.18, we’re making
some important changes in that direction:
- [React hooks that return immutable data](#react-hooks-immutable-data)
- [React selector APIs](#react-selector-apis)
- [React Suspense support](#react-suspense-support)
- [Improved core performance](#improved-core-performance)
- [Specialized React hooks for optimized use cases](#react-specialized-hooks)
The new APIs we’re introducing here solve many subtle and not-so-subtle pain
points. We heard your feedback, and think we have shipped something awesome that
you’ll love.
## New React hooks that return immutable data [#react-hooks-immutable-data]
With 0.18, we’re introducing two main new hooks: `useStorage` and `useMutation`,
which should make reading and writing to Storage much more natural in a React
world. The biggest conceptual shift is that the `useStorage` hook lets you
consume data using normal JavaScript data structures (objects, arrays, maps)
that are immutable.
This means you’ll no longer have to deal with `LiveObject`, `LiveList`, or
`LiveMap` when reading data—only when mutating!
While the `useObject`, `useList`, and `useMap` hooks will still work in 0.18, we
recommend migrating to `useStorage` and `useMutation`. We’ve written
[a step-by-step guide](/docs/guides/upgrading/0.18) to help you migrate. If
you’re stuck, please reach out to us on
[GitHub](https://github.com/liveblocks/liveblocks), and we’ll lend you a hand!
### `useStorage`
This improves the developer experience significantly, enabling you to turn code
that looks like this…
```tsx
// ❌ Before
function Component() {
const scientist = useObject("scientist");
if (scientist == null) {
return null;
}
const pets = scientist.get("pets").toArray();
// ["🐶", "🐈"]
}
```
into code that looks like this…
```tsx
// ✅ Now
function Component() {
const pets = useStorage((root) => root.scientist.pets);
// ["🐶", "🐈"]
}
```
Much better, right?
But that’s not all. Rerendering your components when nested data—like our
scientist’s pets list—changes was a true head breaker before. This required
extra helper components, manual subscriptions, and manual conversion to “normal”
JavaScript arrays.
```tsx
// ❌ Before
function Component() {
const scientist = useObject("scientist");
if (scientist == null) {
return null;
}
return ;
}
function Pets({ livePets }) {
const room = useRoom();
const [pets, setPets] = useState(livePets.toArray());
useEffect(() => {
return room.subscribe(livePets, () => {
setPets(livePets.toArray());
});
}, [room, livePets]);
}
```
Now, rerendering your component when data changes is automatic, even for deeply
nested data.
```tsx
// ✅ Now
function Component() {
const pets = useStorage((root) => root.scientist.pets);
// ["🐶", "🐈"]
}
```
`useStorage` is also helpful when you need to derive a computed value from
different objects. Previously, it took some manual setup to ensure the component
would automatically rerender when either of those values changed.
```tsx
// ❌ Before
function Component() {
const objA = useObject("a");
const objB = useObject("b");
const room = useRoom();
const [sum, setSum] = useState();
// ^^^ We’re trying to compute the result of a.x + b.x in here
useEffect(() => {
function onChange() {
setSum(objA.get("x") + objB.get("x"));
}
const unsubA = room.subscribe(objA, onChange);
const unsubB = room.subscribe(objB, onChange);
return () => {
unsubA();
unsubB();
};
}, [room, objA, objB]);
}
```
The code can now be simplified as follow to rerender automatically any time
`a.x` or `b.x` changes, but not more often.
```js
// ✅ Now
function Component() {
const sum = useStorage((root) => root.a.x + root.b.x);
}
```
Now, this is fully automatic. Or should we say, automagic? `useStorage` feels
right at home in React now: say bye to those redundant `useEffect` with
`room.subscribe` hooks!
### `useMutation`
Now that reading from the Liveblocks storage state is all read-only and no
longer returns mutable data structures, how do we mutate things? The answer is
the new `useMutation` hook.
It’s almost like a normal React `useCallback`, but it provides you access to the
mutable Storage root through the first callback argument. For instance, here is
what a fill action could look like in a design tool. Simply pass the id and the
color of the shape you want to fill.
```tsx
const fill = useMutation(
// Note the second and third arguments
({ storage, setMyPresence }, shapeId: string, color: string) => {
storage.get("shapes").get(shapeId).set("fill", color);
setMyPresence({ lastUsedColor: color });
},
[]
);
return