Velt Comments Best Practices

Comprehensive implementation guide for Velt's collaborative comments feature in React and Next.js applications. Contains 36 rules across 9 categories, prioritized by impact to guide automated code generation and integration patterns.

When to Apply

Reference these guidelines when:

• Adding collaborative commenting to a React/Next.js application
• Implementing any Velt comment mode (Freestyle, Popover, Stream, Text, Page, Inline)
• Integrating comments with rich text editors (TipTap, SlateJS, Lexical)
• Adding comments to media players (Video, Lottie animations)
• Adding comments to charts (Highcharts, ChartJS, Nivo)
• Building custom comment interfaces with standalone components

Rule Categories by Priority

Quick Reference

1. Core Setup (CRITICAL)

• core-provider-setup - Initialize VeltProvider with API key
• core-authentication - Authenticate users before using comments
• core-document-setup - Configure document context for comments

2. Comment Modes (HIGH)

• mode-freestyle - Pin comments anywhere on page
• mode-popover - Google Sheets-style cell comments
• mode-stream - Google Docs-style sidebar stream
• mode-text - Text highlight comments
• mode-page - Page-level comments via sidebar
• mode-inline-comments - Traditional inline thread style
• mode-tiptap - TipTap editor integration
• mode-slatejs - SlateJS editor integration
• mode-lexical - Lexical editor integration
• mode-canvas - Canvas/drawing comments
• mode-lottie-player - Lottie animation frame comments
• mode-video-player-prebuilt - Velt prebuilt video player
• mode-video-player-custom - Custom video player integration
• mode-chart-highcharts - Highcharts data point comments
• mode-chart-chartjs - ChartJS data point comments
• mode-chart-nivo - Nivo charts data point comments
• mode-chart-custom - Custom chart integration

3. Standalone Components (MEDIUM-HIGH)

• standalone-comment-pin - Manual comment pin positioning
• standalone-comment-thread - Render comment threads
• standalone-comment-composer - Add comments programmatically

4. Comment Surfaces (MEDIUM-HIGH)

• surface-sidebar - Comments sidebar component
• surface-sidebar-button - Toggle sidebar button

5. UI Customization (MEDIUM)

• ui-comment-dialog - Customize comment dialog
• ui-comment-bubble - Customize comment bubble
• ui-wireframes - Use wireframe components

6. Data Model (MEDIUM)

• data-context-metadata - Add custom metadata
• data-comment-annotations - Work with annotations
• data-filtering-grouping - Filter and group comments

7. Debugging & Testing (LOW-MEDIUM)

• debug-common-issues - Common issues and solutions
• debug-verification - Verification checklist

8. Moderation & Permissions (LOW)

• permissions-private-mode - Control global comment visibility with enablePrivateMode/disablePrivateMode and update per-annotation visibility with updateVisibility
• permissions-comment-saved-event - Subscribe to the commentSaved event for reliable post-persist side-effects (webhooks, analytics, external sync)

9. Attachments & Reactions (MEDIUM)

• attach-download-control - Control attachment download behavior and intercept clicks

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-provider-setup.md
rules/shared/mode/mode-popover.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Source pointers to official documentation

Compiled Documents

• AGENTS.md — Compressed index of all rules with file paths (start here)
• AGENTS.full.md — Full verbose guide with all rules expanded inline