In this tutorial, we’ll build an Excalidraw-style collaborative whiteboard using Next.js, HTML5 Canvas, and Velt. You’ll add real-time features like live cursors, comments, presence, and huddles directly into your app. Instead of wiring everything manually, we’ll use Velt MCP and AI agents to handle the integration. We’ll also look at how CRDT-based sync keeps everything in real time.

By the end, you’ll have a fully working multi-user canvas app with production-ready collaboration built in.

What we are building

• Excalidraw-style infinite whiteboard
• Real-time collaboration with cursors, comments, huddle, notifications, and presence
• Multi-user canvas with shared state

Why add collaboration to Canvas apps

• Single-user by default: Most canvas apps work locally and don’t support multiple users out of the box
• Real-time sync is complex: Handling state sync, conflicts, and updates across users is not trivial
• Lack of shared context: Without comments, cursors, and presence, collaboration feels disconnected

Why use Velt

Velt is a collaboration SDK that lets you add real-time, multi-user features directly into your app without building the backend infrastructure yourself. It handles presence, syncing, communication, and UI components out of the box, so you can focus on your product.

• Drop-in collaboration layer: Add features like comments, cursors, and presence without building from scratch
• Real-time features built in: Cursors, comments, presence, notifications, and huddles
• CRDT-based sync support: Enables conflict-free real-time state updates for multi-user apps
• AI-powered setup with MCP: Use Velt MCP and agent skills to automatically install and configure features
• No infra needed: No need to manage WebSockets, sync engines, or backend services
• Customizable UI components: Easily integrate collaboration UI into your existing design system

Prerequisites

• Node.js 18+
• Velt API key (from Velt dashboard)
• AI coding editor (Anitgravity is used in this demo)
• Basic React and TypeScript knowledge

Setting up the project

• Clone the repository - https://github.com/Studio1HQ/Velt-Demos/tree/main/excalidraw-velt-demo
• Run npm install
• And then run npm run dev
• Now, open http://localhost:3000

Tutorial: Building Velt-powered Excalidraw-like App

Step 1: Set up Velt MCP

Velt MCP lets your editor (Antigravity) run the Velt installer and guide the integration.

Now, add the Velt MCP installer to Antigravity using the command below:

npx -y @velt-js/mcp-installer

Add it to the Antigravity MCP server configuration with command: "npx" and args: ["-y", "@velt-js/mcp-installer"].

Also, Velt Agent Skills guides the AI on what to implement using best practices, while MCP gives it access to the tools needed to actually execute those changes. Together, they make the integration accurate, structured, and reliable. We have both installed and will be used accordingly.

Get your Velt API key:

• Go to the Velt Dashboard
• Create a project
• Copy your API key

Add it to your .env:

NEXT_PUBLIC_VELT_API_KEY=your_api_key_here

Step 2: Start Velt installation using AI

Now that MCP is set up, we can let the AI agent handle the Velt integration for us.

Open your editor (Antigravity) and type:

install velt

This triggers the Velt MCP installer, which runs as a guided setup inside your editor.

Instead of manually adding SDKs and wiring things, the agent walks you through the setup step by step.

It will ask you for a few inputs:

• Your project directory
• Your Velt API key and auth token
• The features you want to enable (comments, presence, cursors, CRDT, etc.)
• Where to place the VeltProvider (recommended: app/page.tsx)
• UI placement preferences (like corner position)

You can answer each step directly in chat. The flow is simple and guided.

Step 3: Provide the prompt for MCP

At this point, we already have a working whiteboard built manually. Now, instead of integrating Velt step by step ourselves, we use Velt Agent Skills to analyze this existing app and plan how collaboration should be added.

In your editor, after running install velt, provide the following prompt:

I want to start the Velt integration. Review my project structure and use your Velt Agent Skills to plan the CRDT store implementation.

Once you provide this, the agent starts analyzing your codebase. It looks at how your canvas is structured, how state is managed, and where real-time sync can be introduced. Based on this, it generates an integration plan tailored to your whiteboard.

Instead of manually deciding how to structure CRDT or where to wire Velt, the agent uses its skills to plan it correctly for your app.

After reviewing the plan, you can approve it, and the agent will apply the changes step by step.

Step 4: Understand the existing project structure

Before we look at what MCP added, let us understand how this project is structured. Since the agent analyzes your codebase before integrating Velt, this gives context for what it is working with.

The project is organized into three main folders: app, components, and lib.

• The app/ folder contains the core application logic. This is where the whiteboard is rendered and all canvas interactions like drawing, selecting, and updating elements are handled.
• The components/ folder contains UI elements and collaboration integrations. This is where Velt features are connected to your app, including user identity, comments, and UI-level controls.
• The lib/ folder handles state management and shared logic. It manages canvas data, document context, and sync-ready state, making it easier to extend the app with real-time collaboration.

Step 5: Add real-time collaboration features (Using MCP)

Now that the whiteboard is working, we layer Velt on top to make it collaborative. This is where users start seeing each other, interacting in real time, and sharing context.

After you provide the prompt and approve the plan, the MCP installer integrates Velt into your project. It sets up the foundation required for collaboration to work correctly with your existing whiteboard.

Presence and cursors

In app/layout.tsx, the VeltProvider enables real-time awareness across your app. Then in VeltSetup.tsx, each user is identified using. This is what allows Velt to track who is online.

Learn more here

'use client'
import React, { useEffect, useState, Suspense } from "react";
import {
  VeltProvider,
  useSetDocument,
  VeltCursor,
  useVeltClient,
} from "@veltdev/react";
import { useCurrentDocument } from "@/lib/useCurrentDocument";
import { TEST_USERS } from "@/lib/users";
import { useSearchParams } from "next/navigation";

function VeltIdentity({ children }: { children: React.ReactNode }) {
  const { documentId } = useCurrentDocument();
  useSetDocument(documentId ?? "default-whiteboard");
  return <>{children}</>;
}

function VeltProviderInner({ children }: { children: React.ReactNode }) {
  const searchParams = useSearchParams();
  const [user, setUser] = useState(TEST_USERS[0]);

  useEffect(() => {
    const userIndex = searchParams.get("user");
    if (userIndex) {
      const index = parseInt(userIndex);
      if (!isNaN(index) && TEST_USERS[index]) {
        setUser(TEST_USERS[index]);
      }
    } else {
      // Fallback or default behavior
    }
  }, [searchParams]);

  return (
    <VeltProvider
      apiKey={process.env.NEXT_PUBLIC_VELT_API_KEY!}
      authProvider={{
        user: user,
      }}
    >
      <VeltIdentity>
        {/* <VeltCursor /> */}
        {children}
      </VeltIdentity>
    </VeltProvider>
  );
}

export function VeltSetup({ children }: { children: React.ReactNode }) {
  return (
    <Suspense fallback={null}>
      <VeltProviderInner>{children}</VeltProviderInner>
    </Suspense>
  );
}

Once identity is set, Velt automatically shows:

• Active users (avatars)
• Live cursor positions

You don’t have to manually sync cursor movement. Velt handles that internally based on user sessions.

Canvas comments

Comments are one of the most important parts of a canvas app.

"use client";

import { useCommentAnnotations, VeltCommentPin } from "@veltdev/react";
import { Point } from "@/lib/types";
import { useWhiteboardStore } from "@/lib/useWhiteboardStore";

interface CanvasCommentLayerProps {
  zoom: number;
  pan: Point;
}

In CanvasCommentLayer.tsx, comments are rendered as an overlay on top of the canvas. Instead of attaching comments to DOM elements, we attach them to canvas coordinates.

 {
              // Use bounds or specific fields
              // Normalized rect provided by normalizeRect helper? not available here easily.
              // Just use raw coords if available, or approximate.
              // Rect/Ellipse/Diamond have x1,y1,x2,y2 usually?
              // Wait, types.ts says DrawingElement...
              // Let's assume standard shape properties
              if (
                "x1" in element &&
                "y1" in element &&
                "x2" in element &&
                "y2" in element
              ) {
                worldX = (element.x1 + element.x2) / 2;
                worldY = (element.y1 + element.y2) / 2;
              }
            } else if (element.type === "line" || element.type === "arrow") {
              worldX = (element.x1 + element.x2) / 2;
              worldY = (element.y1 + element.y2) / 2;
            }
          }
        }

        if (typeof worldX !== "number" || typeof worldY !== "number") {
          return null;
        }

        const screenX = (worldX + pan.x) * zoom;
        const screenY = (worldY + pan.y) * zoom;

        return (
          <div
            key={annotation.annotationId}
            style={{
              position: "absolute",
              left: `${screenX}px`,
              top: `${screenY}px`,
              transform: "translate(-50%, -100%)",
              zIndex: 50,
              pointerEvents: "auto",
            }}
          >
            <VeltCommentPin annotationId={annotation.annotationId} />
          </div>
        );
      })}
    </div>
  );

From app[/page.tsx](https://github.com/Studio1HQ/Velt-Demos/blob/main/excalidraw-velt-demo/app/page.tsx), you trigger comments like this:

• Capture the (x, y) position on click
• Pass context to Velt
• Optionally attach to a specific element using elementId

This enables:

• Freeform comments anywhere on the canvas
• Context-aware discussions linked to shapes

This is very similar to how tools like Miro or Figma handle comments.

Sidebar and UI controls

These files handle user-facing UI around collaboration.

• ProfileMenu.tsx shows user identity and active participants
• ThemeToggle.tsx syncs your app theme with Velt UI

ProfileMenu.tsx

"use client";

import React, { useEffect, useState } from "react";
import { ChevronDown, User, Check, LogOut, RefreshCwIcon } from "lucide-react";
// import { useVeltClient } from "@veltdev/react";
import { TEST_USERS } from "@/lib/users";

export function ProfileMenu() {
  const [isOpen, setIsOpen] = useState(false);
  const [currentUser, setCurrentUser] = useState(TEST_USERS[0]); // Default to first user

  // Initialize from URL on mount
  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const userIndex = params.get("user");
    if (userIndex) {
      const index = parseInt(userIndex);
      if (!isNaN(index) && TEST_USERS[index]) {
        setCurrentUser(TEST_USERS[index]);
      }
    }
  }, []);

  const handleUserSelect = (user: (typeof TEST_USERS)[0], index: number) => {
    setCurrentUser(user);
    setIsOpen(false);

    // Update URL and reload to ensure clean session isolation via VeltProvider authProvider
    const url = new URL(window.location.href);
    url.searchParams.set("user", index.toString());
    window.location.href = url.toString();
  };

Velt components (like comments sidebar) automatically adapt to your app’s theme. This keeps the experience consistent across your UI and Velt overlays.

Notifications and huddle

Velt also provides built-in tools for:

• Notifications (activity updates)
• Huddle (voice/video collaboration)

You can add these as UI buttons in your toolbar. Once added:

• Notifications show real-time updates (comments, mentions, etc.)
• Huddle lets users start live audio/video sessions inside your app

No extra backend setup is needed. These features are already part of the Velt SDK.

You can see this here in page.tsx

 <div className="mx-1 h-6 w-px bg-slate-200 dark:bg-neutral-800" />
        <div className="flex items-center gap-1">
          <VeltCommentTool darkMode={isDark} />
          <VeltHuddleTool darkMode={isDark} />
          <VeltNotificationsTool darkMode={isDark} />
        </div>
      </section>

Step 6: CRDT-based state sync

Up to this point, the whiteboard works, and collaboration features like comments and presence are in place. But for a real collaborative canvas, the most important piece is shared state. Every shape, line, or text element needs to stay in sync across all users in real time.

This is where CRDT comes in.

In a typical canvas app, state lives locally. When a user draws something, it updates only their view. To make this collaborative, we need a shared state that all users can read and write to.

In useWhiteboardStore.ts, instead of using local state, we use Velt’s CRDT hook:

This creates a shared store that is automatically synced across all connected users.

The id acts as a unique identifier for this piece of state. As long as users are in the same document, they are all connected to this store. The map structure is used to store canvas elements, where each element is indexed by its ID.

"use client";

import { useCallback, useEffect, useMemo, useRef } from "react";
import { useVeltCrdtStore } from "@veltdev/crdt-react";
import type { DrawingElement } from "./types";

type ElementMap = Record<string, DrawingElement>;

export function useWhiteboardStore() {
  const { value, update } = useVeltCrdtStore<ElementMap>({
    id: "whiteboard-elements",
    type: "map",
    initialValue: {},
  });

  const elements: DrawingElement[] = useMemo(
    () => Object.values(value ?? {}).sort((a, b) => a.id.localeCompare(b.id)),
    [value],
  );

  const valueRef = useRef<ElementMap>(value ?? {});

  useEffect(() => {
    valueRef.current = value ?? {};
  }, [value]);

When a user draws a new shape or updates an existing one, the change is not stored locally. Instead, it is written to the CRDT store.

Functions like adding or updating elements internally call the update function provided by useVeltCrdtStore. Once updated, the change is automatically propagated to every other user connected to the same session.

const addElement = useCallback(
    (el: DrawingElement) => {
      update({ ...valueRef.current, [el.id]: el });
    },
    [update],
  );

  const updateElement = useCallback(
    (el: DrawingElement) => {
      update({ ...valueRef.current, [el.id]: el });
    },
    [update],
  );

  const deleteElement = useCallback(
    (id: string) => {
      const next = { ...valueRef.current };
      delete next[id];
      update(next);
    },
    [update],
  );

  return { elements, addElement, updateElement, deleteElement, rawMap: value };

There is no need to manage WebSockets, events, or manual syncing. Velt handles all of that behind the scenes.

The storageProxy.ts file acts as a thin abstraction layer between your canvas logic and the shared store. Instead of directly interacting with the CRDT store everywhere, this layer helps keep the code clean and organized.

It separates:

• Canvas logic
• State update logic

This makes the system easier to maintain and extend.

"use client";

/**
 * Validates if the code is running in a browser environment
 */
const isBrowser = typeof window !== "undefined";

/**
 * Proxies localStorage to redirect specific keys to sessionStorage
 * This allows Velt to have isolated sessions per tab (using sessionStorage)
 * while the rest of the app continues to use localStorage.
 */
export function initStorageProxy() {
  if (!isBrowser) return;

  // Store the original localStorage implementation
  const originalLocalStorage = window.localStorage;
  const originalSessionStorage = window.sessionStorage;

  // Keys that should be redirected to sessionStorage
  // Velt uses keys starting with 'velt', 'snippyly', or '_v' (e.g., _viu, _vv)
  // Also proxying firebase keys as Velt likely uses them for auth/presence
  const isVeltKey = (key: string) => {
    const k = key.toLowerCase();
    return (
      k.startsWith("velt") ||
      k.startsWith("snippyly") ||
      k.startsWith("_v") ||
      k.startsWith("firebase")
    );
  };

Step 7: Multi-user simulation

The user setup lives in lib/users.ts. This file defines a small set of users with basic details like name, color, and avatar. These are used by Velt to represent each participant across features like cursors, comments, and presence.

In components/velt/VeltSetup.tsx, one of these users is selected when the app loads. A random user is picked and passed to Velt. This is what establishes the session.

export const TEST_USERS = [
  {
    userId: "user1",
    name: "Robin",
    email: "robin@velt.dev",
    photoUrl:
      "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=800&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8cG9ydHJhaXR8ZW58MHx8MHx8fDA%3D",
    color: "#F97316", // Orange
    organizationId: "excalidraw-demo",
  },
  {
    userId: "user2",
    name: "Alicia",
    email: "alicia@velt.dev",
    photoUrl:
      "https://images.unsplash.com/photo-1531746020798-e6953c6e8e04?q=80&w=1364&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
    color: "#3B82F6", // Blue
    organizationId: "excalidraw-demo",
  },
];

Every time the app loads, a different user can be assigned. From Velt’s perspective, each session is now a unique participant in the same document.

Step 8: Run and test the app

Now let’s run the app and see everything working together.

Start the development server:

npm run dev

Once the app is running, open it in your browser at http://localhost:3000.

To test collaboration, open the same app in another window. You can use an incognito tab or a different browser. Each session will act as a different user.

As you interact with the canvas, you’ll start noticing the real-time behavior. Drawing a shape in one window reflects instantly in the other. You’ll see users appearing in presence, and comments syncing across both sessions.

At this point, your whiteboard is fully collaborative, with multiple users interacting on the same canvas in real time.

Here is the deployed link for you to explore the demo.

Wrapping up

We started with a simple canvas and turned it into a fully collaborative whiteboard. Along the way, we added real-time cursors, presence, comments, notifications, and even voice huddles using Velt. Instead of building sync logic and infra from scratch, we used Velt MCP and agent skills to handle the heavy lifting and get everything working quickly.

The key takeaway here is simple. You don’t need to spend weeks building real-time systems to make your app collaborative. With the right tools, you can focus on your product and let the platform handle sync, presence, and communication.

From here, you can extend this further:

• Connect real authentication instead of simulated users
• Improve CRDT logic for more complex canvas operations
• Customize Velt UI components to match your product

If you’re building any product where users need to collaborate, this is a pattern worth exploring.

What would your app look like if it supported real-time collaboration from day one?

Try Velt and start adding features like comments, presence, cursors, CRDT sync, notifications, and huddles to your app.