Build a Real-Time Excalidraw-like Collaborative Canvas using Velt MCP and Antigravity🎉

개요

이 튜토리얼은 Next.js, HTML5 Canvas, Velt MCP 및 AI 에이전트를 사용하여 Excalidraw 스타일의 실시간 협업 캔버스 화이트보드를 구축하는 방법을 안내합니다.

주요 내용

• 협업 기능 통합의 복잡성: 일반적인 캔버스 앱은 기본적으로 단일 사용자용이며, 실시간 동기화, 상태 충돌 처리, 사용자 간 업데이트 관리는 복잡합니다. 또한, 댓글, 커서, 참여 정보(presence) 없이는 협업이 단절된 느낌을 줄 수 있습니다.
• Velt SDK 활용: Velt는 백엔드 인프라 구축 없이 앱에 실시간, 다중 사용자 기능을 추가할 수 있는 협업 SDK입니다. Presence, 동기화, 통신, UI 컴포넌트 등을 제공하여 개발자가 제품에 집중할 수 있게 합니다.
• Velt MCP와 AI 에이전트: Velt MCP는 AI 코딩 에디터(Antigravity)에서 Velt 설치 프로그램을 실행하고 통합을 안내하도록 합니다. Velt Agent Skills는 AI에 구현할 사항에 대한 지침을 제공하며, MCP는 AI에 필요한 도구에 접근 권한을 부여하여 정확하고 구조화된 통합을 가능하게 합니다.
• 프로젝트 설정: Node.js 18+, Velt API 키, AI 코딩 에디터(Antigravity) 및 React/TypeScript 기본 지식이 필요합니다. GitHub 리포지토리를 클론하고, npm install 및 npm run dev 명령어로 프로젝트를 설정합니다.
• Velt MCP 설치 및 설정: npx -y @velt-js/mcp-installer 명령어로 MCP 설치 프로그램을 추가하고, Antigravity MCP 서버 설정에 "npx"와 ["-y", "@velt-js/mcp-installer"] 인자를 추가합니다. Velt API 키를 복사하여 .env 파일에 NEXT_PUBLIC_VELT_API_KEY=your_api_key_here 형식으로 추가합니다.
• AI를 이용한 Velt 설치: 에디터에서 install velt 명령어를 실행하면 MCP 설치 프로그램이 시작됩니다. AI 에이전트가 프로젝트 디렉토리, Velt API 키, 활성화할 기능(댓글, presence, 커서, CRDT 등), VeltProvider 배치 위치 등을 단계별로 안내합니다.
• 기존 프로젝트 구조 분석: Velt 통합 전에 AI 에이전트는 app/ (핵심 앱 로직), components/ (UI 요소 및 협업 통합), lib/ (상태 관리 및 공유 로직) 폴더로 구성된 프로젝트 구조를 분석합니다.
• 실시간 협업 기능 추가 (MCP 사용):
• Presence 및 커서: app/layout.tsx의 VeltProvider와 VeltSetup.tsx에서 사용자 식별을 통해 Velt가 온라인 사용자를 추적하고, 활성 사용자 아바타와 실시간 커서 위치를 자동으로 표시합니다.
• 캔버스 댓글: CanvasCommentLayer.tsx에서 댓글을 캔버스 좌표에 첨부하여 렌더링하며, app/page.tsx에서 클릭 시 좌표를 캡처하고 Velt에 컨텍스트를 전달하여 댓글을 생성합니다. VeltCommentPin 컴포넌트를 사용하여 댓글을 표시합니다.
• 사이드바 및 UI 제어: ProfileMenu.tsx, ThemeToggle.tsx 등은 사용자 인터페이스를 관리하며, Velt 컴포넌트는 앱 테마에 맞게 자동으로 조정됩니다.
• 알림 및 Huddle: Velt는 알림(활동 업데이트) 및 Huddle(음성/영상 협업) 기능을 제공하며, UI 버튼을 통해 추가할 수 있습니다.
• CRDT 기반 상태 동기화: useWhiteboardStore.ts에서 Velt의 useVeltCrdtStore 훅을 사용하여 모든 사용자가 동일한 상태를 공유하고 실시간으로 업데이트되는 공유 스토어를 생성합니다. addElement, updateElement, deleteElement 함수를 통해 변경 사항을 CRDT 스토어에 기록하고, Velt가 이를 자동으로 전파합니다. storageProxy.ts는 캔버스 로직과 공유 스토어 간의 추상화 계층 역할을 합니다.
• 다중 사용자 시뮬레이션: lib/users.ts에서 정의된 사용자를 VeltSetup.tsx에서 선택하여 각 세션을 고유한 참가자로 설정합니다.
• 앱 실행 및 테스트: 개발 서버를 실행하고( npm run dev), 다른 브라우저 창이나 시크릿 모드를 사용하여 여러 사용자가 동시에 캔버스에 상호 작용하며 실시간 협업 기능을 테스트합니다.

시사점

이 튜토리얼은 Velt와 같은 SDK를 활용하면 복잡한 실시간 동기화 및 협업 시스템을 처음부터 구축할 필요 없이 개발자가 제품 자체에 집중하여 빠르게 협업 기능을 구현할 수 있음을 보여줍니다.