velt-comments-best-practices_skill

Overview

This skill documents implementation patterns and best practices for integrating Velt collaborative comments into React, Next.js, and web applications. It prioritizes 33 pragmatic rules across nine categories to guide setup, comment modes, editor integrations, media/chart comments, and UI/data patterns. Use it to standardize reliable, secure, and extensible comment features.

How this skill works

The skill inspects common integration points and prescribes code patterns: provider and authentication setup, document context configuration, and mode-specific integrations (Freestyle, Popover, Stream, Text, Page, Inline). It also covers rich text editor adapters (TipTap, Slate, Lexical), media and chart comment hooks, standalone components, UI customization, data modeling, and debugging checks. Rules are ordered by priority so you apply critical setup first and lower-impact items later.

When to use it

• Adding collaborative commenting to a React or Next.js app
• Implementing any Velt comment mode (Freestyle, Popover, Stream, Text, Page, Inline)
• Integrating comments into rich text editors like TipTap, SlateJS, or Lexical
• Attaching comments to media players (video, Lottie) or charts (Highcharts, ChartJS, Nivo)
• Building standalone comment components or customizing comment surfaces

Best practices

• Initialize VeltProvider with an API key and enforce user authentication before exposing comment features
• Configure and pass a document context so comments are scoped and resolvable across sessions
• Choose the right comment mode for content: popovers for point comments, stream/sidebar for document review, freestyle for visual pinning
• Integrate editor adapters using established adapters (TipTap/Slate/Lexical) to preserve annotations and selection state
• Expose standalone components (pin, thread, composer) to allow programmatic comment control and reuse
• Add metadata and filtering options to the data model for robust grouping, permissions, and moderation

Example use cases

• Code review UI with stream sidebar and inline text highlights using mode-stream and mode-text
• Video player with frame-anchored comments and timeline pins using mode-video-player-custom
• Design feedback tool where users pin comments on images or canvas using mode-freestyle and mode-canvas
• Embedded rich-text editor comments in a CMS using mode-tiptap or mode-slatejs with data-comment-annotations
• Interactive dashboards where users comment on chart points (Highcharts/ChartJS/Nivo) using the respective chart modes