Zulip is known for keeping conversations organized. Topic-based threads, clear context, and async-friendly discussions make it a favorite for technical and distributed teams. Unlike traditional chat apps, conversations in Zulip stay readable even as teams scale.

Recreating this experience can be a bit difficult. Real-time messaging, user presence, inline comments, and notifications usually require a complex backend and real-time infrastructure.

In this tutorial, we will build a Zulip-style collaborative chat application using Next.js, Tailwind CSS, and Velt. Next.js powers the UI and application structure, while Velt adds collaboration features like presence, comments, and notifications without writing backend code.

By the end, you will have a working chat interface inspired by Zulip, with real-time collaboration built in and ready to extend.

Why Zulip’s Approach Works

Zulip’s design solves a problem most chat tools struggle with: conversations getting messy over time.

Instead of long, linear message streams, Zulip organizes discussions into topics. Each message belongs to a clear context, so conversations stay focused and easy to follow even days or weeks later.

Three ideas make this work especially well:

• Real-time collaboration: Messages, comments, and updates appear instantly for everyone in the channel.
• Context-rich discussions: Replies stay tied to a specific topic or message, so feedback does not get lost in the noise.
• Visible presence: You always know who is online and actively participating, which makes collaboration feel immediate and shared.

What makes this challenging to build in a SaaS product is not the UI, but the infrastructure behind it. Real-time messaging, presence tracking, comments, and notifications typically require WebSockets, backend event systems, data synchronization, and careful handling of concurrent users. Building and maintaining this reliably can take significant engineering effort.

In this tutorial, we recreate Zulip’s collaborative behavior without building that infrastructure ourselves, by using Velt as the collaboration layer.

What We’re Building With

Before we dive into the code, let’s quickly look at the tools we’ll use and why they fit this project well.

• Next.js: Next.js gives us a solid foundation for building interactive applications. With the App Router, we get a clean layout structure and client-side interactivity that works well for chat-style interfaces.
• React: React handles the UI composition and state updates. The chat interface, message list, and user interactions all rely on simple, predictable React patterns.
• Tailwind CSS: Tailwind helps us build a clean and modern UI quickly. It keeps styling close to the components and makes it easy to adjust layouts, spacing, and themes without writing custom CSS.
• shadcn ui (powered by Radix UI): These provide accessible, reusable UI primitives like buttons, dropdowns, and avatars. They give us a polished look without locking us into heavy component libraries.
• Zustand: Zustand is used for lightweight state management. In this project, it manages demo users and allows us to switch between them to test real-time collaboration.
• Velt: Velt is the key piece. Instead of building real-time infrastructure ourselves, Velt provides presence, comments, notifications, and collaboration out of the box. Once integrated, features like reactions, read status, and threaded comments work automatically without writing extra backend or real-time code.

Together, this stack lets us focus on the chat experience and UI, while Velt handles the collaboration layer behind the scenes.

Prerequisites

To follow along with this tutorial, you’ll need:

• Node.js (v16 or later) installed on your machine
• Basic familiarity with Next.js, React, and TypeScript
• A Velt account (you can sign up for free at velt.dev)
• Working knowledge of Tailwind CSS fundamentals

You do not need:

• Prior experience with Velt
• Any backend or database setup
• Experience building real-time systems

We’ll walk through the collaboration setup step by step, and the app runs entirely on the frontend.

Project Setup

Instead of scaffolding a new project from scratch, we’ll start from an existing Zulip style chat app that already has the UI and collaboration logic wired up. This lets us focus on understanding how the pieces fit together.

Clone the Repository

Begin by cloning the project and moving into the directory:

gitclone https://github.com/Studio1HQ/zulip-velt
cd zulip-velt

Install Dependencies

Install all required dependencies using npm:

npm install

This will install Next.js, Tailwind CSS, shadcn ui components, Zustand for state management, and the Velt SDK used for collaboration features.

Configure the Velt API Key

Velt requires a public API key to enable collaboration features like presence, comments, and notifications.

Create a .env.local file in the root of the project and add:

NEXT_PUBLIC_VELT_ID=your_velt_api_key_here

You can generate this key from the Velt dashboard after creating a free account.

Once the key is added, restart the development server if it is already running.

Run the App Locally

Start the development server:

npm run dev

Open your browser and visit:

http://localhost:3000

You should now see a Zulip-style chat interface with channels on the left, a message area in the center, and collaboration controls in the header.

At this point, the UI is already functional. In the next sections, we’ll break down how the app is structured and how Velt is integrated to power real-time collaboration without any backend setup.

Project Setup

At a high level, the project is divided into five main parts:

• app: Handles routing, layouts, and global configuration using the Next.js App Router
• components: Contains all reusable UI and chat-related components
• helper: Manages demo user data and user switching logic
• hooks: Stores custom React hooks such as theme management
• lib: Holds small utility functions used across the app

Let’s take a closer look at the most important folders we’ll work with in this tutorial.

Understanding the App Router and Layout Setup

This project uses the Next.js App Router, which organizes the application using layouts and pages instead of traditional route files. If you are new to the App Router, don’t worry. We’ll focus only on what matters for this app.

The key idea is simple: layouts wrap pages, and this is where we place Velt and theme handling.

In this project, there are two layout files, each with a different responsibility.

layout.tsx is the root layout for the entire application. It defines the HTML structure, metadata, and global styles.

"use client";

import { ThemeProvider } from "@/hooks/use-theme";
import { VeltProvider } from "@veltdev/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_ID || ""}>
      <ThemeProvider>{children}</ThemeProvider>
    </VeltProvider>
  );
}

page.tsx - This file renders the main chat interface. You’ll see it importing layout and chat components and placing them on the page.

"use client"

import { useState, useEffect } from 'react'
import { Header } from '@/components/layout/header'
import { Sidebar } from '@/components/layout/sidebar'
import { ChatArea } from '@/components/chat/chat-area'

export default function Home() {
  const [isSidebarOpen, setIsSidebarOpen] = useState(true)
  const [isSidebarCollapsed, setIsSidebarCollapsed] = useState(false)
  const [isMobile, setIsMobile] = useState(false)

  useEffect(() => {
    const checkMobile = () => {
      const mobile = window.innerWidth < 768
      setIsMobile(mobile)
      if (mobile) {
        setIsSidebarOpen(false)
        setIsSidebarCollapsed(false)
      }
    }

    checkMobile()
    window.addEventListener('resize', checkMobile)
    return () => window.removeEventListener('resize', checkMobile)
  }, [])

  const toggleSidebar = () => {
    if (isMobile) {
      setIsSidebarOpen(!isSidebarOpen)
    } else {
      if (isSidebarCollapsed) {
        setIsSidebarCollapsed(false)
      } else if (isSidebarOpen) {
        setIsSidebarCollapsed(true)
      } else {
        setIsSidebarOpen(true)
      }
    }
  }

  const closeSidebar = () => {
    if (isMobile) {
      setIsSidebarOpen(false)
    }
  }

  return (
    <div className="h-screen flex flex-col bg-background">
      <Header 
        onToggleSidebar={toggleSidebar}
        isSidebarOpen={isSidebarOpen}
        isMobile={isMobile}
      />
      <div className="flex-1 flex overflow-hidden">
        <Sidebar 
          isOpen={isSidebarOpen}
          isCollapsed={isSidebarCollapsed}
          isMobile={isMobile}
          onClose={closeSidebar}
        />
        <ChatArea />
      </div>
    </div>
  )
}

• app/layout.tsx is the global shell
• app/(app)/layout.tsx is where Velt is initialized
• page.tsx is where the chat UI begins
• Providers are placed at layout level so all components can access them

Building the Chat Interface with Components

Most of the Zulip-style experience in this app is built using reusable React components. Each part of the interface has a clear responsibility, which makes the code easier to read and extend.

We’ll focus on three areas:

• The chat area where messages appear
• The message component itself
• The layout components that shape the overall UI

Chat Area:

chat-area.tsx - This component is responsible for rendering the list of messages and attaching collaboration features to them.

message.tsx - Each message in the chat is rendered as its own component. This keeps the UI modular and makes it easy to attach collaboration features at the message level.

Layout Components:

The layout of the app is built using two main components: a header and a sidebar.

• The sidebar represents Zulip style channels and navigation.
• The header is where collaboration controls live.

Inside the header, you’ll see Velt components like:

<VeltPresence />
<VeltNotificationsTool />
<VeltCommentsSidebar />
<VeltSidebarButton />

What these do:

• VeltPresence shows who is currently online
• VeltNotificationsTool displays collaboration notifications
• VeltCommentsSidebar Opens a panel with all comments
• VeltSidebarButton toggles the comments sidebar

All of these work automatically once Velt is initialized at the layout level.

import {
  VeltPresence,
  VeltNotificationsTool,
  VeltSidebarButton,
  VeltCommentsSidebar,
  useVeltClient,
} from "@veltdev/react";
import { names, userIds, useUserStore } from "@/helper/userdb";

interface HeaderProps {
  onToggleSidebar: () => void;
  isSidebarOpen: boolean;
  isMobile: boolean;
}

export function Header({
  onToggleSidebar,
  isSidebarOpen,
  isMobile,
}: HeaderProps) {
  const { theme } = useTheme();
  const { user, setUser } = useUserStore();
  const { client } = useVeltClient();
  const prevUserRef = useRef(user);
  const isInitializingRef = useRef(false); // Prevent overlapping initialization calls

Client Initialization, User Identification, and Document Setting

 // Handle Velt client initialization, user identification, and document setting
  useEffect(() => {
    if (!client || !user || isInitializingRef.current) {
      console.log("Velt init skipped:", {
        client: !!client,
        user: !!user,
        initializing: isInitializingRef.current,
      });
      return;
    }

    const initializeVelt = async () => {
      isInitializingRef.current = true;
      try {
        // Detect user switch
        const isUserSwitch = prevUserRef.current?.uid !== user.uid;
        prevUserRef.current = user;

        console.log("Starting Velt init for user:", user.uid, { isUserSwitch });

        // Re-identify the user (handles initial and switches)
        const veltUser = {
          userId: user.uid,
          organizationId: "organization_id",
          name: user.displayName,
          email: user.email,
          photoUrl: user.photoUrl,
        };
        await client.identify(veltUser);
        console.log("Velt user identified:", veltUser.userId);
        await client.setDocuments([
          {
            id: "zulip-velt",
            metadata: { documentName: "zulip-velt" },
          },
        ]);
        console.log("Velt documents set: zulip-velt");
      } catch (error) {
        console.error("Error initializing Velt:", error);
      } finally {
        isInitializingRef.current = false;
      }
    };

    initializeVelt();
  }, [client, user]); // Re-run on client or user change

Reusable UI Components

To keep the chat interface clean and consistent, this project uses a set of reusable UI components. These components handle common UI patterns like buttons, inputs, avatars, and scroll areas.

Instead of building these from scratch, the project uses shadcn ui, which is a collection of accessible, unstyled components built on top of Radix UI. This approach gives us flexibility while keeping the UI consistent.

All reusable UI components live inside the components/ui folder.

• Reusable UI primitives: Shared building blocks like buttons, inputs, avatars, and dropdowns used across the app to keep styling consistent.
• Built with shadcn ui (powered by Radix UI): Accessible, unstyled components that provide behavior and keyboard support without locking the design.
• Scroll handling for chat: The ScrollArea component manages smooth scrolling for long message lists in the chat view.
• Separation of concerns: UI components handle appearance and interaction, while chat and layout components focus on structure and logic.
• Easy to extend and customize: Updating a UI component in this folder automatically updates its usage across the entire app.

User Management for Collaboration Testing

To test real-time collaboration features like presence, comments, and notifications, we need a way to simulate multiple users. Instead of setting up a full authentication system, this project uses a simple and beginner-friendly approach with predefined users.

User state is managed using Zustand, a lightweight state management library.

import { create } from "zustand";
import { persist } from "zustand/middleware";

export type User = {
  uid: string;
  displayName: string;
  email: string;
  photoUrl?: string;
};

export interface UserStore {
  user: User | null;
  setUser: (user: User) => void;
}

export const userIds = ["user001", "user002"];
export const names = ["Nany", "Mary"];

export const useUserStore = create<UserStore>()(
  persist(
    (set) => ({
      user: null,
      setUser: (user) => set({ user }),
    }),
    {
      name: "user-storage",
    }
  )
);

Theme Management with useTheme

Modern apps usually support both light and dark themes, and this project follows the same pattern. Theme state is managed using a custom React hook, which keeps the logic reusable and easy to maintain.

The theme logic lives inside a single file.

The theme is:

• Stored in React state
• Loaded from localStorage on page load
• Saved back to localStorage when changed

This ensures the user’s theme preference persists across page refreshes.

Syncing Theme with Velt

The theme value is also passed to Velt components, allowing them to automatically switch between light and dark modes.

This means:

• The app UI and Velt UI stay visually consistent
• No extra styling logic is required for collaboration components
• Once the hook is set up, theme changes propagate everywhere.

Utility Functions

The lib folder contains small helper utilities that are shared across the application. In this project, it mainly exists to support reusable UI components and keep common logic out of individual files. The utilities in this file are primarily related to class name handling. When working with Tailwind CSS and reusable components, it’s common to conditionally apply multiple class names.

Running the App and Testing the Output

Now that we’ve walked through the project structure and key files, it’s time to run the app and verify that everything works as expected.

Seeing the app in action makes the collaboration features easier to understand in the next sections.

From the project root, run:

npm run dev

Once the server starts, open your browser and navigate to:

http://localhost:3000

You should see a Zulip style chat interface with:

• A sidebar for channels
• A header with user controls
• A central chat area for messages

To test collaboration features, open the app in two browser windows or one normal window and one incognito window.

Use the user switcher in the header to change between demo users such as Nany and Mary.

Each window should represent a different user.

Try the following actions:

• Presence: Notice user avatars appear in the header when multiple users are online.
• Comments: Hover over a message and add a comment. The comment should appear instantly in both windows.
• Notifications: Add a comment in one window and check the notification bell in the other.
• Theme Switching: Toggle between light and dark mode and observe that both the app and Velt components update correctly.

How It Works

Here’s a simple view of what happens when the app runs:

• The app loads and initializes Velt using the API key in the layout
• A demo user is selected using the Zustand store
• Velt identifies the active user and associates them with the app
• A shared document context is set for collaboration
• Messages render in the chat area
• Comments, presence, and notifications are automatically tracked by Velt
• Updates sync instantly across all connected clients

The key idea is that the app focuses on UI and user flow, while Velt handles real-time synchronization and collaboration logic.

Collaborative Features You Get Automatically

Once Velt is integrated, collaboration features start working without writing additional backend or real-time code.

These features are available out of the box:

• Inline comments: Add comments directly on chat messages and view them in context.
• User presence: See who is currently online and active in the chat.
• Notifications: Get notified when someone comments or interacts.
• Reactions and comment status: React to comments and mark them as resolved or active.
• Read awareness: See when comments have been viewed by other users.

All of these features work automatically once Velt is set up.

Things to Note Before Shipping to Production

Before using this setup in a real product, keep the following in mind:

• Replace demo users with a real authentication system
• Identify users using real user IDs and metadata
• Use dynamic document IDs instead of a hardcoded value
• Add permissions to control who can view or comment
• Handle error states when collaboration services are unavailable
• Review Velt customization options to match your product UI
• Test performance with multiple concurrent users

These steps ensure the app scales safely beyond a demo environment.

Demo Video

You can see the completed Zulip style chat app with real-time collaboration in action here:

Live Demo:

https://zulip-velt-chat.vercel.app/

This demo shows user switching, comments, presence, notifications, and theme support working together.

Conclusion

Zulip demonstrates how powerful chat can be when collaboration is built into the experience. Organized conversations, clear context, and real-time awareness turn chat from simple messaging into a system teams can rely on.

For builders, the real challenge is not the UI. It is the collaboration layer behind it. Features like real-time sync, presence tracking, inline comments, notifications, and reactions usually require complex infrastructure and long development cycles. This is especially true when building a chat-based SaaS product.

In this tutorial, we focused on that exact problem. Instead of rebuilding collaboration from scratch, we showed how to add Zulip-style collaborative features inside a chat application using Next.js and a modern frontend stack, while delegating the hard real-time problems to Velt.

The result is a working chat app where collaboration feels native, but the code stays simple and frontend-focused.

Key Takeaways

• Clean component structure makes complex apps easier to understand
• Collaboration does not need custom real-time infrastructure
• Velt enables comments, presence, notifications, and more out of the box
• Frontend-focused development speeds up experimentation and iteration

If you are building a chat app, internal tool, or collaborative product, Velt lets you focus on your core experience instead of infrastructure.

Try building with Velt and add collaboration to your app in minutes at velt.dev.