Introduction

Modern apps need built-in collaboration. Users expect to comment on text, see who is online, and receive updates without switching tools. If your editor lacks these features, discussions move to Slack or email. Context gets lost. Engagement drops.

In this guide, we will build a Dropbox Paper-style collaborative editor. You will add inline comments to selected text, show real-time presence, and enable in-app notifications. The stack uses Next.js with the App Router, TipTap for rich text editing, and Velt for collaboration infrastructure.

Building real-time collaboration from scratch is complex and time-consuming. Tools like Velt abstract that complexity so you can focus on product logic instead of infrastructure.

By the end, you will have a fully working collaborative editor running locally.

Tech Stack Overview

This project uses a modern React-based stack built for real-time interaction. Each tool has a clear responsibility and works well in collaborative environments.

• Next.js (App Router): Provides the application structure and routing layer. The App Router makes it easy to organize layouts, wrap the app with providers, and manage client components cleanly.
• TipTap Editor: A highly extensible rich text editor built on ProseMirror. It allows precise control over marks and extensions, which makes it ideal for inline commenting and collaborative annotations.
• Velt SDK: Handles real-time comments, presence, notifications, and collaboration state. It abstracts the backend complexity required for multi-user interaction.
• Tailwind CSS + shadcn/ui: Enables fast UI development with consistent styling and accessible components.
• Zustand: Manages lightweight global state, such as switching between predefined users for collaboration simulation.

Project Structure Walkthrough

Before diving into the implementation, it helps to understand how the project is organized. The structure separates layout, collaboration logic, and UI components so each concern stays isolated.

• app/ — Layout and Velt Initialization

  Contains the root layout and App Router setup. This is where VeltProvider wraps the application and initializes the SDK with your API key and active user.

• components/ — UI and Core Features

  Holds the main building blocks of the interface, including the editor and the top navigation bar.

• paper-document.tsx — TipTap + Velt Integration

  Implements the rich text editor and registers the Velt TipTap extension. This file handles rendering comments and adding new ones to selected text.

• top-bar.tsx — Presence, Notifications, Sidebar Controls

  Displays active users, shows notifications, and provides access to the comments sidebar.

• helper/userdb.ts — User Switching Logic

  Uses Zustand to manage predefined users and simulate multi-user collaboration.

What is Velt?

Velt is a collaboration SDK that lets you add real-time features like comments, presence, and notifications directly into your product. Instead of building backend infrastructure for multi-user sync, conflict resolution, and event handling, you integrate Velt components and ship collaboration features in days.

Below are the key features used in this project:

• Contextual Comments: Add inline comments to specific UI elements or selected text. Comments stay attached to their exact position, enabling precise discussions inside the app.
• Real-Time Presence: Show who is currently viewing or interacting with the document. Presence indicators update instantly across users.
• Notifications System: Trigger in-app notifications for mentions, replies, and updates. Keeps users informed without leaving the product.
• Comments Sidebar: Centralized panel to view, manage, and navigate all comment threads within the document.
• Multi-User Collaboration Support: Handles user identity, ownership of comments, and live updates so multiple users can interact with the same document seamlessly.

Local Setup (Quick Start)

First, install the Velt client SDK:

npm install @veltdev/client

Velt must be initialized at the root of your application so every component can access the collaboration state. In a Next.js App Router project, this means wrapping your app inside VeltProvider in the root layout.

Create a .env file in the root directory and add your Velt API key:

NEXT_PUBLIC_VELT_ID = your_velt_api_key_here

Clone the repository and install the dependencies:

git clone https://github.com/Studio1HQ/dropbox-velt.git
cd dropbox-velt
npm install

Start the development server:

npm run dev

Open http://localhost:3000 in your browser.

If you're using Velt Agent Skills or MCP-based setup, manual installation steps can be skipped since the AI handles SDK wiring and configuration. This demo uses the standard manual SDK integration.

Wrapping the App with VeltProvider

Before integrating Velt features into the editor, Velt must be available across the application. In this project, the provider is added inside the root layout so every component can access collaboration features.

This setup lives in app/layout.tsx. The VeltProvider wraps the entire app and receives the API key from the environment variable. The ThemeProvider is nested inside it so both theme and collaboration context are globally available.

The provider must sit at the top level because presence, comments, and notifications rely on shared context. If it is mounted deeper in the tree, some components will not receive real-time updates.

"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>
  );
}

Now that Velt is initialized globally, we can integrate it directly into the TipTap editor.

Adding Inline Comments to TipTap

The core collaboration logic lives inside components/paper-document.tsx. This file initializes the TipTap editor and connects it to Velt using the TipTap comments plugin.

"use client";

import { useEditor, EditorContent, BubbleMenu } from "@tiptap/react";
import { StarterKit } from "@tiptap/starter-kit";
import {
  TiptapVeltComments,
  renderComments,
  addComment,
} from "@veltdev/tiptap-velt-comments";
import { useCommentAnnotations } from "@veltdev/react";
import { useEffect } from "react";

import { Avatar, AvatarFallback } from "./ui/avatar";
import { Separator } from "./ui/separator";
import { Button } from "./ui/button";
import {
  MessageCircle,
} from "lucide-react";

const EDITOR_ID = "paper-document-editor";

Start by installing @veltdev/tiptap-velt-comments. This package bridges TipTap’s editor state with Velt’s comment system. Once installed, register the TiptapVeltComments extension inside the editor configuration. This enables comment marks on selected text and connects them to Velt’s backend.

Each editor instance must have a unique editor ID. In this project, a fixed document ID is used so comments stay tied to the same document across sessions.

When the editor loads, renderComments syncs and displays existing annotations from Velt. When a user selects text and clicks the comment action in the bubble menu, addComment creates a new contextual thread linked to that selection.

The bubble menu integration ensures users can comment directly on highlighted text. This creates a Google Docs-style inline commenting experience inside your own app.

export function PaperDocument() {
  const editor = useEditor({
    extensions: [
      StarterKit,
      TiptapVeltComments.configure({
        persistVeltMarks: false,
      }),
    ],
    content: {
      type: "doc",
      content: [
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "This document contains all the essential information and resources for our current project. Feel free to add comments, suggestions, or ask questions using the tools on the right.",
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Overview" }],
        },
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "Our team is working on creating a comprehensive solution that addresses the key challenges in collaborative document editing and file sharing. This project aims to deliver a seamless experience for teams of all sizes.",
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Key Features" }],
        },
        {
          type: "bulletList",
          content: [
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Real-time collaboration with team members" }] },
              ],
            },
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Inline comments and feedback" }] },
              ],
            },
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Version history and rollback capabilities" }] },
              ],
            },
            {
              type: "listItem",
              content: [
                { type: "paragraph", content: [{ type: "text", text: "Secure sharing with granular permissions" }] },
              ],
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Timeline" }],
        },
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "The project is divided into multiple phases, each with specific deliverables and milestones. We're currently in Phase 2, focusing on core functionality and user experience improvements."
            },
          ],
        },
        {
          type: "heading",
          attrs: { level: 2 },
          content: [{ type: "text", text: "Resources" }],
        },
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text:
                "Below you'll find all the files and documents related to this project. Click on any item to preview or download it."
            },
          ],
        },
      ],
    },
    autofocus: false,
    immediatelyRender: false,
  });

Adding Presence & Notifications

Collaboration is not just about comments. Users need awareness and updates in real time. In this project, these features are implemented inside components/top-bar.tsx and connected to the editor view.

"use client";
import {
  useVeltClient,
  VeltCommentsSidebar,
  VeltNotificationsTool,
  VeltPresence,
  VeltSidebarButton,
} from "@veltdev/react";

import { names, userIds, useUserStore } from "@/helper/userdb";
import { Rocket, Share, User } from "lucide-react";
import React, { useEffect, useMemo, useRef } from "react";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { FileText, Share2, MoreHorizontal, ChevronDown } from "lucide-react";
import { Button } from "./ui/button";
import useTheme, { ThemeToggleButton } from "@/hooks/use-theme";

VeltPresence displays the users currently viewing the document. It renders active user avatars in the top bar and updates instantly when someone joins or leaves. This gives immediate visibility into who is online and working on the same content.

VeltNotificationsTool adds an in-app notification system. It surfaces mentions, replies, and comment activity without requiring page refreshes. Users stay informed while remaining inside the document.

VeltSidebarButton toggles the comments panel. When clicked, it opens VeltCommentsSidebar, which lists all comment threads in one place. Users can review discussions, jump to specific annotations, and manage conversations efficiently.

export function TopBar() {
  const { theme } = useTheme();
  const { user, setUser } = useUserStore();
  const { client } = useVeltClient();
  const prevUserRef = useRef(user);
  const isInitializingRef = useRef(false); // Prevent overlapping initialization calls

  const predefinedUsers = useMemo(
    () =>
      userIds.map((uid, index) => {
        const avatarUrls = [
          "https://api.dicebear.com/7.x/pixel-art/svg?seed=Nany",
          "https://api.dicebear.com/7.x/pixel-art/svg?seed=Mary",
        ];
        return {
          uid: uid,
          displayName: names[index],
          email: `${names[index].toLowerCase()}@gmail.com`,
          photoUrl: avatarUrls[index],
        };
      }),
    []
  );

  // Initialize user from localStorage if none exists
  useEffect(() => {
    if (typeof window !== "undefined" && !user) {
      const storedUser = localStorage.getItem("user-storage");
      if (!storedUser) {
        setUser(predefinedUsers[0]);
      }
    }
  }, [user, setUser, predefinedUsers]);

  // 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: "drop-box-velt",
            metadata: { documentName: "drop-box-velt" },
          },
        ]);
        console.log("Velt documents set: drop-box-velt");
      } catch (error) {
        console.error("Error initializing Velt:", error);
      } finally {
        isInitializingRef.current = false;
      }
    };

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

Together, these components create a real-time collaborative environment with visibility, context, and structured discussion.

Multi-User Switching (Simulating Collaboration)

To demonstrate collaboration locally, this project simulates multiple users using a simple state store. The logic lives inside helper/userdb.ts, where predefined users like Nany and Mary are defined with unique IDs and avatars.

The store is built with Zustand. It keeps track of the currently active user and exposes a method to switch between them. When you select a different user from the dropdown in components/top-bar.tsx, the active user state updates instantly.

Because VeltProvider receives the current userId, switching users changes how Velt identifies the session. Presence indicators update automatically, and new comments are attributed to the selected user. Existing comments also display correct ownership based on user identity.

This setup allows you to test real-time presence, comment ownership, and notification behavior on localhost without needing multiple devices or accounts.

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",
    }
  )
);

How Everything Works Together

At a high level, the editor, Velt SDK, and UI components form a connected real-time collaboration loop. Each layer has a clear responsibility, but they operate as a single system.

• Editor → Velt Plugin → Comments

  The TipTap editor in components/paper-document.tsx registers the Velt comments extension. When a user selects text and adds a comment, the plugin sends the annotation to Velt. Velt syncs it across sessions, and the editor renders it inline.

• User Change → Presence Update

  The active user is managed in helper/userdb.ts. When switching users from components/top-bar.tsx, the userId passed to VeltProvider changes. Velt immediately updates presence and ensures new comments reflect the correct ownership.

• Comment → Sidebar → Notification

  When a comment is created, it appears inline and is listed inside VeltCommentsSidebar, and triggers updates in VeltNotificationsTool. All views stay synchronized in real time.

• Provider → SDK Lifecycle

  VeltProvider in app/layout.tsx manages initialization and global collaboration state. It maintains the real-time connection and ensures all components receive updates consistently.

Demo

Final Result & Takeaways

We built a Dropbox Paper-style collaborative editor with inline comments, real-time presence, and in-app notifications. The entire collaboration layer runs inside the product without relying on external tools. Instead of building real-time infrastructure from scratch, Velt handles synchronization, ownership, and updates. This pattern applies to CMS platforms, dashboards, internal tools, document editors, and any product that needs structured collaboration.

If you are building a collaborative feature, try integrating Velt and ship production-ready comments, presence, and notifications in days instead of months.

Resources

• Velt Documentation
• GitHub Repository
• Live Demo: Try the application yourself