With Liveblocks 1.11, we’re updating our authentication recommendations, in aid
of helping you build scalable applications as easily as possible. This update
also includes a number of small improvements and additions to Comments,
refinements for Yjs subdocuments, and a way to rename your existing room IDs.
- [Authentication recommendations](#authentication-recommendations)
- [Comments improvements](#comments-improvements)
- [Yjs subdocuments refinements](#yjs-subdocument-refinements)
- [Rename room IDs](#rename-room-ids)
## Upgrade now
Start using the new features now by updating each Liveblocks package in your
project to the `@latest` version.
```bash
npm install @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-comments@latest liveblocks/node@latest
```
There are no breaking changes in Liveblocks 1.11.
## Authentication recommendations [#authentication-recommendations]
Authentication is imperative for securing your application, and Liveblocks
provides this through two different methods, allowing you to authorize and grant
permissions to your users. We’ve taken some time to update our documentation, as
we’d like to be crystal clear about choosing the correct authentication method
for your application.
### Overview
The two methods we provide are
[access token authentication](/docs/authentication/access-token) and
[ID token authentication](/docs/authentication/id-token).
#### Access tokens
Access token authentication allows you to handle permissions yourself. It’s best
for prototyping, and is great if you need only simple permissions. We always
recommend using a [naming pattern](/docs/authentication/access-token#permission)
when granting access.
If you’re using
[`liveblocks.prepareSession`](/docs/api-reference/liveblocks-node#access-tokens)
in your application, that means you’re using access tokens.
#### ID tokens
ID token authentication allows you to set complex room permissions for different
groups and users, and Liveblocks will check the permissions for you. This is
best for apps that use share menus, such as those in Google Docs or Figma.
If you’re using
[`liveblocks.identifyUser`](/docs/api-reference/liveblocks-node#id-tokens) in
your application, that means you’re using ID tokens.
### Public key
If you’re using your public API key in production, we also recommend switching
over to your secret API key instead. Your public key makes it possible for end
users to access any room’s data, and if your application has permissions, this
should be avoided.
```tsx
// Using public API key
const client = createClient({
publicApiKey: "pk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
});
```
You can tell if you’re using your public key by checking
[`createClient`](/docs/api-reference/liveblocks-client#createClientPublicKey) in
your config file. It’s still okay to use your public key on public pages that
require no permissions.
### Learn more
To learn more about any of our new authentication recommendations, see our
rewritten [authentication documentation](/docs/authentication).
## Comments improvements [#comments-improvements]
In Liveblocks 1.11, we’re making a number of improvements to
[Comments](/comments), mostly related to user experience.
### Scroll into view
The default Comments components will now scroll into view, and be highlighted,
when a [Notification](/docs/products/comments/email-notifications) is clicked.
A comment scrolling into view when a notification is clicked.
This works by checking if the current page’s URL contains a comment’s ID hash
which Notifications automatically adds for you. However, you can also use this
feature yourself by manually adding the hash, for example with `#cm_b26Gr7...`:
```
https://example.com/document#cm_b26Gr7...
```
Scroll into view is enabled by default, but you can disable it by passing a
`scrollOnLoad` option to
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads).
```tsx
function Component() {
const { threads } = useThreads({ scrollOnLoad: false });
// ...
}
```
### Mark as read
The
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
default component now offers a dropdown menu allowing you to mark a notification
as read.
Alongside this addition, we’ve also improved the UI of the component, making it
easier to use at particularly narrow widths.
### Notifications example
We’ve built a minimal Notifications example for Comments which is a great
starting place to learn how to add a notifications inbox to your application.
Highlights of the new notifications example’s interface.
You can find the code, and a live demo, in our
[examples gallery](/examples/comments-notifications/nextjs-comments-notifications).
## Yjs subdocument refinements [#yjs-subdocument-refinements]
[Liveblocks Yjs](/document/yjs) allows you to create subdocuments, which are
essentially Yjs documents that are nested inside each other. We’ve refined the
way subdocuments can be accessed in our
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) package, and written a
new guide that takes you through how to use them.
### New methods
In this update, we’re changing
[`liveblocks.getYjsAsBinaryUpdate`](/docs/api-reference/liveblocks-node#get-rooms-roomId-ydoc-binary)
and
[`liveblocks.sendYjsBinaryUpdate`](/docs/api-reference/liveblocks-node#put-rooms-roomId-ydoc)
to support subdocuments. These functions allow you to fetch and edit Yjs
subdocuments on the server without connecting via WebSockets.
```tsx
// The unique identifier (`guid`) of your subdocument
const guid = "c4a755...";
// Get your subdocument
const subdoc = new Y.Doc();
const update = liveblocks.getYjsDocumentAsBinaryUpdate("my-room-id", { guid });
Y.applyUpdate(subdoc, new Uint8Array(update));
// Make changes to your subdocument, for example:
subdoc.getText("my-text").insert(0, "Hello world");
// Send the changes to Liveblocks, and other clients
const subdocChanges = Y.encodeStateAsUpdate(subdoc);
liveblocks.sendYjsBinaryUpdate("my-room-id", subdocChanges, { guid });
```
### New guide
To learn how to use subdocuments on both client & server, and when to use them,
make sure to read our detailed
[new guide on subdocuments](/docs/guides/how-to-use-yjs-subdocuments).
## Rename Room IDs [#rename-room-ids]
It’s now possible to change the ID of any existing room, a feature that is
particularly helpful if you’re switching to an access token
[naming pattern](/docs/authentication/access-token#Naming-pattern). You can do
this by using
[`liveblocks.updateRoomId`](/docs/api-reference/liveblocks-node#post-rooms-update-roomId)
or our new
[update room ID REST API](/docs/api-reference/rest-api-endpoints#post-rooms-update-roomId).
```ts
const room = await liveblocks.updateRoomId({
roomId: "my-room-id",
newRoomId: "new-room-id",
});
// { type: "room", id: "new-room-id", ... }
console.log(room);
```
To implement this, make sure to read our guide on
[migrating your room IDs](/docs/guides/how-to-rename-room-ids-and-successfully-migrate-users),
as we explain how to smoothly transition users that are currently connected.
## Upgrade
There are no breaking changes in this update, and you can start using the new
features now. Update every Liveblocks package in your project to the `@latest`
version to get started.
```bash
npm install @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-comments@latest liveblocks/node@latest
```
If you’d like to add Comments to your application, make sure to check out our
guides and examples.
- [Get started with Comments](/docs/get-started/nextjs-comments)
- [Comments examples](/examples/browse/comments)
- [Comments guides](/docs/guides?topics=comments)
## Contributors
Huge thanks to everyone who contributed, and specifically to
[Adrien Gaudon](https://x.com/adigau31),
[Florent Lefebvre](https://x.com/florentpml),
[Guillaume Salles](https://x.com/guillaume_slls),
[Marc Bouchenoire](https://x.com/marcbouchenoire),
[Nimesh Nayaju](https://x.com/nayajunimesh),
[Olivier Foucherot](https://www.linkedin.com/in/olivier-foucherot) for their
work on Comments and Notifications. Keep checking the
[changelog](https://github.com/liveblocks/liveblocks/blob/main/CHANGELOG.md) for
the full release notes—see you next time!