Liveblocks 1.12: Advanced filtering and custom notifications

Liveblocks 1.12 introduces additions to Comments and example updates.

• Advanced thread and room filtering: Filter with queries on client and server.
• Custom notifications alpha: Send custom notifications to InboxNotification.
• Inbox notification thread hook: Get thread data that’s part of a notification.
• Comments canvas example: Add draggable comments to your application.
• Next.js Starter Kit update: Uses /app directory, and is much simpler.

Upgrade now

Upgrade now by updating each Liveblocks package to the @latest version.

$npm install @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-comments@latest liveblocks/node@latest

There are no breaking changes in Liveblocks 1.12.

Advanced thread and room filtering

Liveblocks 1.12 introduces query-based thread filtering to Comments, allowing you to create advanced UI components for filtering threads by their metadata.

To enable filtering by metadata, pass a query option to useThreads. Only threads that match the query will be returned, and you can even use a startsWith option to find partial metadata string matches. In this example, we’re filtering for unresolved threads that are assigned to a specific string.

import { useThreads } from "../liveblocks.config";
function Component() {  const { threads } = useThreads({    query: {      metadata: {        resolved: false,        assignedTo: {          startsWith: "liveblocks:design:",        },      },    },  });
  // ...}

Filtering is also enabled on the server using liveblocks.getThreads, working in the exact same way.

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
export async function POST() {  const { data: threads } = await getThreads({    query: {      metadata: {        resolved: false,        assignedTo: {          startsWith: "liveblocks:design:",        },      },    },  });
  // ...}

If you’re using our REST API directly, you can filter using our new query language.

Advanced room filtering

Liveblocks 1.12 also enables advanced room filtering on the server, allowing you to fetch any rooms that match a specific room ID naming pattern. In this example we’re filtering for "whiteboard" rooms, and then using startsWith to only match rooms with IDs that begin with "liveblocks:"

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
export async function POST() {  const { data: rooms } = liveblocks.getRooms({    query: {      roomId: {        startsWith: "liveblocks:",      },      metadata: {        type: "whiteboard",      },    },  });
  // ...}

If you’re using our REST API directly, you can filter using our new query language.

Custom notifications alpha

When using Comments, you can choose to render relevant inbox notifications for users when threads update. We’re extending these notifications, allowing you to send any kind of custom notification, and we’ve just released the alpha in Liveblocks 1.12.

To send a custom notification, call liveblocks.triggerInboxNotification on the server. Here’s an example that notifies users about a file upload.

await liveblocks.triggerInboxNotification({  kind: "$fileUploaded",  userId: "pierre@example.com",  subjectId: "file-upload-6f9sg7...",
  activityData: {    name: "pitch-deck.pdf",    uploadedBy: "steven@example.com",    url: "https://example.com/pitch-deck.pdf",  },});

Then in React, you can render a custom notification for $fileUploaded, accessing the custom activityData that was set.

<InboxNotification kinds={{ $fileUploaded: FileUploadedNotification }} />

function FileUploadedNotification(props) {  const activityData = props.inboxNotification.activities[0].data;  const { user } = useUser(activityData.uploadedBy);
  return (    <InboxNotification.Custom      title={`${user.name} uploaded a new file`}      aside={<InboxNotification.Avatar userId={user.id} />}      {...props}    >      <a href={activityData.url}>🗎 {activityData.name}</a>    </InboxNotification.Custom>  );}

We generally recommend using <InboxNotification.Custom> to render notifications, as it allows you to place your content in slots that work with the existing design system. However, you can also use completely custom styling, should you choose.

<InboxNotification  kinds={{    $fileUploaded: (props) => {      const { name, url } = props.inboxNotification.activities[0].data;      return <a href={url}>{name} has been uploaded</a>;    },  }}/>

We’ll be sharing more about custom notifications soon, as we continue to work on it. Make sure to join our Discord server or follow us on Twitter and LinkedIn for updates and upcoming content.

Inbox notification thread hook

An advanced use case for inbox notifications is building your own custom components for thread notifications. Previously for these components, you’d have to implement your own logic to fetch thread information, but we’ve now created a new useInboxNotificationThread hook which will handle this for you.

import { useInboxNotificationThread } from "../liveblocks.config";
function Component({ inboxNotification }) {  const thread = useInboxNotificationThread(inboxNotification.id);
  // { id: "th_d75sF3...", metadata: { ... }, ... }  console.log(thread);
  // Use your thread data  // ...}

Canvas Comments example

We’ve built a new Comments example detailing how to build a canvas with draggable threads. With a quick copy-and-paste, you can add this to your application—the code and a live demo are available in our examples gallery!

We also have a similar, more complex example, that allows you to pin threads to HTML elements.

Next.js Starter Kit update

Our Next.js Starter Kit has been completely rewritten and now uses the Next.js /app directory. Just to recap, the Next.js Starter Kit is a great starting point when building your own collaborative application, and highlights how to use every aspect of Liveblocks.

Previously, a number of files were necessary to synchronize types and functionality between client, server, and API endpoints, but thanks to server actions, type-safe functions now work on both server and client.

import { getDocument } from "@/lib/actions";
// Can be used in both browser and Node.jsconst { data, error } = await getDocument({  documentId: "my-document-id",});

Not only has this update greatly shrunk the codebase, but the main bundle size is almost 50% smaller too. To download and deploy the Next.js Starter Kit, run the following command.

$npx create-liveblocks-app@latest --next

You can also try a live demo.

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.

$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
• Comments examples
• Comments guides

Contributors

Huge thanks to everyone who contributed, and specifically to Adrien Gaudon, Florent Lefebvre, Guillaume Salles, Marc Bouchenoire, Nimesh Nayaju, Olivier Foucherot for their work on Comments and Notifications. Keep checking the changelog for the full release notes—see you next time!