Quickstart - Get started with creating a realtime feed using Liveblocks and Next.js

Liveblocks is a realtime collaboration infrastructure for building performant collaborative experiences. Follow the following steps to start adding a realtime feed to your Next.js /app directory application using hooks from @liveblocks/react and methods from @liveblocks/node.

Quickstart

1. Install Liveblocks

   Every package should use the same version.

   Terminal

   npm install @liveblocks/client @liveblocks/node @liveblocks/react

2. Initialize the liveblocks.config.ts file

   We can use this file later to define types for our application.

   Terminal

   npx create-liveblocks-app@latest --init --framework react

3. Define feed message shape

   Inside the new liveblocks.config.ts file, define the data shape for messages in feeds. Any JSON data is supported, and can be used to render UI in your application. In this this guide, we'll define role and content properties, like you’d find in an AI chat.

   liveblocks.config.ts

   // liveblocks.config.tsdeclare global {  interface Liveblocks {    // Data shape for feed messages    FeedMessageData: {      role: "user" | "assistant" | "system";      content: string;    };
       // Add custom metadata to each feed    FeedMetadata: {};  }}
   export {};

4. Create a feed in your back end

   Create a feed in your back end using the createFeed method and send messages with the createFeedMessage method. This snippet simualtes a slow running process then adds a second message. Here we’ve put this in a server action.

   Picture this file as the AI back end of your application. It’s responsible for generating AI responses and adding them into the feed.

   app/actions.ts

   "use server";
   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxx…xxxxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
   export async function newFeed(roomId: string, feedId: string) {  // Create a new feed  const feed = await liveblocks.createFeed({    roomId: roomId,    feedId: feedId,    metadata: {},  });
     // Add a first message  await liveblocks.createFeedMessage({    roomId: roomId,    feedId: feedId,    data: {      role: "assistant",      content: "Hello there",    },  });
     // Simulate a slow running AI process  await new Promise((resolve) => setTimeout(resolve, 3000));
     // Add a second message  await liveblocks.createFeedMessage({    roomId: roomId,    feedId: feedId,    data: {      role: "user",      content: "How can I help you today?",    },  });
     return { feedId };}

5. Render the feed messages

   Now that we’ve defined the data shape, we can start using it. Add useFeedMessages to get a list of feed messages, then loop through them to render their data. Import the newFeed server action into a button to demo creating a new feed.

   app/RealtimeFeed.tsx

   "use client";
   import { useState } from "react";import { useFeedMessages, useRoom } from "@liveblocks/react/suspense";import { newFeed } from "./actions";
   export function RealtimeFeed() {  const { messages } = useFeedMessages(feedId);  const [feedId, setFeedId] = useState("my-feed-id");  const room = useRoom();
     return (    <div>      {messages.map(({ id, data}) => (        <div key={id}>{data.role}: {data.content}</div>      ))}
         <button onClick={() => {        // Create a new feed with a random ID        const newFeedId = crypto.randomUUID()        newFeed(room.id, newFeedId);        setFeedId(newFeedId);      }}>        New feed      </button>    </div>  );}

6. Create a Liveblocks room

   Liveblocks uses the concept of rooms, separate virtual spaces where people collaborate, and to create a realtime experience, multiple users must be connected to the same room. When using Next.js’ /app router, we recommend creating your room in a Room.tsx file in the same directory as your current route.

   Set up a Liveblocks client with LiveblocksProvider, join a room with RoomProvider, and use ClientSideSuspense to add a loading spinner to your app.

   app/Room.tsx

   "use client";
   import { ReactNode } from "react";import {  LiveblocksProvider,  RoomProvider,  ClientSideSuspense,} from "@liveblocks/react/suspense";
   export function Room({ children }: { children: ReactNode }) {  return (    <LiveblocksProvider publicApiKey={"pk_prod_xxxxxxxxxx…xxxxxxxxpk_prod_xxxxxxxxxxxxxxxxxxxxxxxx"}>      <RoomProvider id="my-room-id">        <ClientSideSuspense fallback={<div>Loading…</div>}>          {children}        </ClientSideSuspense>      </RoomProvider>    </LiveblocksProvider>  );}

7. Add the room and feed to your page

   After creating your room file, it’s time to join it. Import your room into your page.tsx file, and place your feed component inside it.

   app/page.tsx

   import { Room } from "./Room";import { RealtimeFeed } from "./RealtimeFeed";
   export default function Page() {  return (    <Room>      <RealtimeFeed />    </Room>  );}

8. Next: authenticate your users and add presence

   Feeds is now set up and working! Each user in your app is still anonymous—the next step is to authenticate each user as they connect, and optionally share their live presence in an avatar stack, cursors, or custom UI.

   Add your users to Comments

9. Optional: read about creating agentic workflows

   Liveblocks can be used to create agentic workflows, where AI agents can collaborate with humans in realtime. This is a powerful way to build collaborative applications with AI, and we’ve detailed various ways to create this.

   Enabling agentic workflows with Liveblocks

What to read next

Congratulations! You’ve set up the foundation to start building a realtime feeds experience for your Next.js application.

• Overview
• API Reference
• Enabling agentic workflows with Liveblocks

Examples using Feeds