velt-comments-best-practices
Velt Comments Best Practices
Comprehensive implementation guide for Velt's collaborative comments feature in React and Next.js applications. Contains 71 rules across 12 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
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Core Setup | CRITICAL | core- |
| 2 | Comment Modes | HIGH | mode- |
| 3 | Standalone Components | MEDIUM-HIGH | standalone- |
| 4 | Comment Surfaces | MEDIUM-HIGH | surface- |
| 5 | UI Customization | MEDIUM | ui- |
| 6 | Data Model | MEDIUM | data- |
| 7 | Debugging & Testing | LOW-MEDIUM | debug- |
| 8 | Moderation & Permissions | LOW | permissions- |
| 9 | Attachments & Reactions | MEDIUM | attach- |
Quick Reference
1. Core Setup (CRITICAL)
core-provider-setup- Initialize VeltProvider with API keycore-authentication- Authenticate users before using commentscore-document-setup- Configure document context for comments
2. Comment Modes (HIGH)
mode-freestyle- Pin comments anywhere on pagemode-popover- Google Sheets-style cell commentsmode-stream- Google Docs-style sidebar streammode-text- Text highlight commentsmode-page- Page-level comments via sidebarmode-inline-comments- Traditional inline thread stylemode-tiptap- TipTap editor integrationmode-slatejs- SlateJS editor integrationmode-lexical- Lexical editor integrationmode-canvas- Canvas/drawing commentsmode-lottie-player- Lottie animation frame commentsmode-video-player-prebuilt- Velt prebuilt video playermode-video-player-custom- Custom video player integrationmode-chart-highcharts- Highcharts data point commentsmode-chart-chartjs- ChartJS data point commentsmode-chart-nivo- Nivo charts data point commentsmode-chart-custom- Custom chart integration
3. Standalone Components (MEDIUM-HIGH)
standalone-comment-pin- Manual comment pin positioningstandalone-comment-thread- Render comment threadsstandalone-comment-composer- Add comments programmatically
4. Comment Surfaces (MEDIUM-HIGH)
surface-sidebar- Comments sidebar componentsurface-sidebar-v2- Primitive-architecture V2 sidebar with 27+ composable primitives, unified filter model, and focused-thread viewsurface-sidebar-button- Toggle sidebar button
5. UI Customization (MEDIUM)
ui-comment-dialog- Customize comment dialogui-comment-bubble- Customize comment bubbleui-wireframes- Use wireframe componentsui-autocomplete-primitives- Use standalone autocomplete primitive components to build custom autocomplete UIs without requiring the full VeltAutocomplete panelui-v2-primitives- Set defaultCondition={false} on V2 primitive sub-components to bypass SDK default show/hide logic when overriding sections in wireframe compositions
6. Data Model (MEDIUM)
data-context-metadata- Add custom metadatadata-comment-annotations- Work with annotationsdata-filtering-grouping- Filter and group commentsdata-activity-action-types- Use CommentActivityActionTypes constant for type-safe comment activity filtering instead of raw stringsdata-trigger-activities- Set triggerActivities on CommentData to auto-create activity records via POST /v2/commentannotations/adddata-comment-annotation-data-provider- Use config-based URL endpoints on CommentAnnotationDataProvider without placeholder callbacks; additionalFields replicates fields to resolver while retaining in Velt storage; fieldsToRemove strips fields from Velt's DB for PII removaldata-agent-fields-query- Use agentFields on CommentRequestQuery to filter getCommentAnnotationCount() to agent-tagged annotations; unread count equals total count when agentFields is set
7. Debugging & Testing (LOW-MEDIUM)
debug-common-issues- Common issues and solutionsdebug-verification- Verification checklist
8. Moderation & Permissions (LOW)
permissions-private-mode- Control global comment visibility with enablePrivateMode/disablePrivateMode and update per-annotation visibility with updateVisibilitypermissions-comment-saved-event- Subscribe to the commentSaved event for reliable post-persist side-effects (webhooks, analytics, external sync)permissions-visibility-option-dropdown- Enable the visibility dropdown in the comment composer to let users select public or private before submitting, and subscribe to visibilityOptionClicked eventspermissions-comment-save-triggered-event- Use commentSaveTriggered for immediate UI feedback (spinners, disabled states) on save button click — before the async database write completespermissions-comment-interaction-events- Prefer past-tense event aliases commentToolClicked and sidebarButtonClicked over the present-tense originals in new codepermissions-anonymous-user-data-provider- Register setAnonymousUserDataProvider() to resolve tagged contact emails to userIds at comment save time
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
More from velt-js/agent-skills
velt-crdt-best-practices
Velt CRDT (Yjs) collaborative editing best practices for real-time applications. This skill should be used when implementing collaborative features using Velt CRDT stores, integrating with editors like Tiptap, BlockNote, CodeMirror, or ReactFlow, or debugging sync issues. Triggers on tasks involving real-time collaboration, multiplayer editing, CRDT stores, or Velt SDK integration.
28velt-setup-best-practices
Velt collaboration SDK setup guide for React, Next.js, Angular, Vue, and HTML applications. Use this skill when setting up Velt for the first time, configuring VeltProvider, implementing user authentication with authProvider and JWT tokens, initializing document collaboration with setDocuments, or debugging Velt setup issues. Triggers on any task involving Velt installation, VeltProvider configuration, auth token generation, document identity setup, or project structure for Velt integration — even if the user doesn't explicitly mention "setup".
26velt-notifications-best-practices
Velt Notifications implementation patterns and best practices for React, Next.js, and web applications. Use when adding in-app notifications, notification panels, email notifications via SendGrid, webhook integrations, or user notification preference management.
25velt-activity-best-practices
Velt Activity Logs implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time activity feeds, custom activity logging, audit trails, CRDT debounce configuration, or server-side activity management via REST API.
7velt-rest-apis-best-practices
Velt REST API v2 and webhook best practices for server-side integration. Use when calling Velt REST API v2 endpoints, generating JWT tokens for frontend authentication, handling Velt webhooks (comment events, huddle events, CRDT updates), managing users/documents/organizations via REST, or implementing server-side Velt operations. Triggers on any task involving Velt REST API, JWT token generation for Velt, Velt webhooks, x-velt-api-key headers, or server-side comment/notification/activity management — even if the user doesn't explicitly say 'REST API'. For the Python SDK (velt-py) for self-hosting, see velt-self-hosting-data-best-practices instead.
5velt-single-editor-mode-best-practices
Velt Single Editor Mode implementation patterns and best practices for React, Next.js, and web applications. Use when implementing exclusive editing access, editor/viewer role management, access request handoff flows, element-level sync control, timeout-based editor transfer, or multi-tab editing restrictions.
5