diff --git a/async-collaboration/comments/customize-behavior.mdx b/async-collaboration/comments/customize-behavior.mdx
index f2177d8b..9346d981 100644
--- a/async-collaboration/comments/customize-behavior.mdx
+++ b/async-collaboration/comments/customize-behavior.mdx
@@ -88,20 +88,19 @@ commentElement.addCommentOnSelectedText();
-
Adds a Comment on a specific element by ID.
To add a comment on a specific element through an API method, use the `addCommentOnElement()` method and pass in an object with the schema shows in the example:
+**Example 1: Add comment with targetElementId only:**
+
-
```jsx
-
const element = {
"targetElement": {
- "elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element)
+ "elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element)
"targetText": "target_text", // optional (pass targetText if you want to add comment on a specific text)
"occurrence": 1, // optional (default: 1) This is relevant for text comment. By default, we will attach comment to the first occurence of the target text in your document. You can change this to attach your comment on a more specific text.
"selectAllContent": true, // Set to `true` if you want to select all the text content of the target element.
@@ -123,8 +122,8 @@ commentElement.addCommentOnElement(element);
-```jsx
+```jsx
const element = {
"targetElement": {
"elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element)
@@ -147,8 +146,6 @@ const commentElement = Velt.getCommentElement();
commentElement.addCommentOnElement(element);
```
-
-
#### addManualComment
@@ -2069,22 +2066,41 @@ Extra fields in the comment context don't prevent a match.
{ product: "cheese", category: "dairy"} ❌ No match (missing field)
```
+**Example**
+
```jsx
+{/* Comment Bubble with Partial Match */}
+
+{/* Comment Tool with Partial Match */}
+
```
```html
+
+
+
+
+
```
diff --git a/async-collaboration/comments/setup/popover.mdx b/async-collaboration/comments/setup/popover.mdx
index 0c4a4a4f..4b7ea4f3 100644
--- a/async-collaboration/comments/setup/popover.mdx
+++ b/async-collaboration/comments/setup/popover.mdx
@@ -4,13 +4,11 @@ title: "Popover Setup"
+## Step 1: Import Comment components
-
+
-
-
-
Import the `VeltComments`, `VeltCommentTool`, and `VeltCommentBubble` components.
```js
@@ -22,347 +20,252 @@ import {
} from '@veltdev/react';
```
-
+
+
+
+No imports needed. The Velt SDK is loaded via script tag.
-
+
+
-Add the `VeltComments` component to the root of your app and mark the `popoverMode` property as `true`.
+## Step 2: Add Comments component with Popover mode
-This component is required to render comments in your app.
+Add the Comments component to the root of your app and enable Popover mode.
-Popover mode means that comments can be attached to specific target elements. The UX pattern is very similar to commenting in Google Sheets.
+This component is required to render comments in your app. Popover mode means comments can be attached to specific target elements (similar to Google Sheets).
+
+
+
```js
```
-
-
+
+
+
+Add the comment component to your template close to the root level of your ``.
+
+```html
+
+
+
+```
+
+
+
+
+## Step 3: Add the Comment Tool component
-There are two patterns to add the `Comment Tool` component with `Popover` comments:
- - Add a `Comment Tool` next to each element you want to have `Popover` comments
- - Have a single `Comment Tool` and use it to pin a `Popover `comment on a particular element
+There are two patterns for adding the Comment Tool:
+- Add a Comment Tool next to each element you want to comment on
+- Have a single Comment Tool and use it to pin comments on elements
### a. Comment Tool next to each element
-- Add a `Comment Tool` near each cell or element you want to comment on. For example, in a table you could add this tool to each cell and show it on hover or right click context menu.
-- Add unique DOM ID to each cell or element component.
-- Set the value of the `targetElementId` prop on Comment Tool as the same unique ID that you added to the cell or element component.
-- When users click on the `Comment Tool`, it will attach a `Comment` to the target element.
+Add a Comment Tool near each cell or element you want to comment on. For example, in a table you could add this tool to each cell and show it on hover or right click context menu.
-
+- Add unique DOM ID to each element
+- Set the `targetElementId` to match the element's ID
+- When users click on the Comment Tool, it attaches a Comment to that element
+- If your app is more complex and cannot have unique IDs for each element (e.g., table cell), you could also use `context` to bind the element and comment with custom metadata, which can then be used to filter, group, and render comments that match specific criteria. [Learn more](/async-collaboration/comments/customize-behavior#aggregation)
+
-Once the `Comment` is added, you will notice a triangle on the top right corner of the element indicating that a `Comment` is present on this element.
+Once the Comment is added, you'll see a triangle on the top right corner of the element.
+
+
```jsx
-
+
-
+
+
+
+```
+
+
+
+
+```html
+
+
+
+
+
+
```
+
+
+
### b. Single Comment Tool
-- Add a `Comment Tool` in a single location such as the navigation bar.
-- Add unique DOM ID and `data-velt-target-comment-element-id` attribute to each cell or element component. Both should have the same value.
-- When users click on the `Comment Tool` and click on the target element, it will attach a `Comment` to it.
-- You can now only add one `Comment Annotation` per element.
+Add a Comment Tool in a single location such as the navigation bar.
+
+- Add unique DOM ID and `data-velt-target-comment-element-id` attribute to each element (both with the same value)
+- When users click on the Comment Tool and then click on the target element, it attaches a Comment to it
+- You can only add one Comment Annotation (thread) per element with this approach
+- If your app is more complex and cannot have unique IDs for each element (e.g., table cell), you could also use `context` to bind the element and comment with custom metadata, which can then be used to filter, group, and render comments that match specific criteria. [Learn more](/async-collaboration/comments/customize-behavior#aggregation)
-If you don't add the `data-velt-target-comment-element-id` attribute, you will be adding multiple `Comment Annotations` on the same element.
+If you don't add the `data-velt-target-comment-element-id` attribute, you will be adding multiple Comment Annotations on the same element.
+
+
+
+
```jsx
-
+
+
+
+```
+
+
+
+```html
+
+
+
+
+
+
```
-
+
+
+
+## Step 4: Add Metadata to the Comment
-
-You can add metadata to the comment, which allows you to:
-- Render additional data on comments
-- Position comment pins manually
+- Render additional data on comments UI
- Create custom UI components
- Enable comment filtering on custom data
-
-There are two ways to add metadata to the comment:
-- Using Comment Tool
-- Using Comment Add Event Callback
+- Use the metadata later when processing notifications
### a. Using Comment Tool
+
+
+
```jsx
-
+
+```
+
+
+
+
+```html
+
```
+
+
+
### b. Using Comment Add Event Callback
-You can learn more about it [here](/async-collaboration/comments/customize-behavior#addcontext).
-
+Learn more about it [here](/async-collaboration/comments/customize-behavior#addcontext).
+
+## Step 5: Add the Comment Bubble component (optional)
-
-Either use this or the default triangle component. Using both could cause some visual ux issues. You can turn off the triangle component by setting the `popoverTriangleComponent` prop to `false` in the `Velt Comments` component.
+Either use this or the default triangle component. Using both could cause visual UX issues. Turn off the triangle by setting `popoverTriangleComponent` to `false` in the Velt Comments component.
The Comment Bubble component:
- Displays a count of replies for a comment thread
-- Must have the same `targetElementId` as its associated element
-- Can be configured to show either total replies or only unread replies
+- Must have the same `targetElementId` or `context` as its associated element and comment tool
+- Can show either total replies or only unread replies
- Can be placed anywhere in your UI
-**Props:** `commentCountType`: This prop allows you to decide which count to display.
-- `total`: Shows the total number of replies. (default)
-- `unread`: Shows the number of unread replies.
+**Props:**
+- `commentCountType`: Which count to display
+ - `total`: Total number of replies (default)
+ - `unread`: Number of unread replies
+
+
+
```js
-
+
-
+
```
-
-
-
-
-
-
-
-You can choose to remove the triangle that appears in `Popover` mode.
-
-By default, the triangle is enabled.
-
-```jsx
-
-```
-
-API Method:
-
-```jsx
-const commentElement = client.getCommentElement();
-commentElement.enablePopoverTriangleComponent();
-commentElement.disablePopoverTriangleComponent();
-```
-
-
-
-
-Test it out by opening the page with Velt components in your browser.
-
-Click on the `Comment Tool` and leave a comment on the target element.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Add the comment component to your template. Try to put it as close to the root level of your ``.
-
-This component is required to render comments in your app.
-
-```html
-
-
-
-```
-
-
-
-
-There are two patterns to add the `Comment Tool` component with `Popover` comments:
- - Add a `Comment Tool` next to each element you want to have `Popover` comments
- - Have a single `Comment Tool` and use it to pin a `Popover `comment on a particular element
-
-### Comment Tool next to each element
-
-In `Popover Mode`, you can add a `Comment Tool` near each cell or element you want to comment on.
-
-Add the ``component on each component where you want to enable commenting.
-
-
-
-For example, in a table you could add this tool to each cell and show it on hover or right click context menu.
-
-You must specify a target element ID which binds the tool to that element. When users click on the `Comment Tool`, it will attach a `Comment` to the target element.
-
-Once the `Comment` is saved, you will notice a triangle on the top right corner of the element indicating that a `Comment` is present on this element.
-
-
+
+
```html
-
-
-
-
-
-
-```
-
-### Single Comment Tool
-
-
-
-
-If you want to have a single `Comment Tool` in a single location such as the navigation bar, you can do so as well.
-
-To do this, add `data-velt-target-comment-element-id` as an attribute on each element you want to add comments on.
-
-Now, when you click on the `Comment Tool` and click on the target element, it will attach a `Popover` comment to the element.
-
-You will now notice that you can only add one `Comment Annotation` per element.
-
-
-If you don't add the `data-velt-target-comment-element-id` attribute, you will be adding multiple `Comment Annotations` on the same element.
-
-
-```jsx
-
-
-
-
-
-
-
-
-
-
-
-```
-
-
-
-
-You can add metadata to the comment, which allows you to:
-- Render additional data on comments
-- Position comment pins manually
-- Create custom UI components
-- Enable comment filtering on custom data
-
-There are two ways to add metadata to the comment:
-- Using Comment Tool
-- Using Comment Add Event Callback
-
-### a. Using Comment Tool
-
-```html
-
-```
-
-### b. Using Comment Add Event Callback
-You can learn more about it [here](/async-collaboration/comments/customize-behavior#addcontext).
-
-
-
-
-
-
-This component accepts a target element ID & binds the comment annotation to it.
-
-It shows the total number of replies in the given comment annotation.
-You also have the option to choose whether to display the total number of replies or just the unread replies.
-
-This gives you a lot of flexibility as you can place this component anywhere and provides a more obvious affordance to your users.
-
-**Props:** `comment-count-type`: This prop allows you to decide which count to display.
-- `total`: Shows the total number of replies. (default)
-- `unread`: Shows the number of unread replies.
-
-```html
-
-
-
+
+ >
-
+
+ >
```
-
-
+
+
+
+### Remove Popover Mode Triangle (optional)
-You can choose to remove the triangle that appears in `Popover` mode.
+You can remove the triangle that appears in Popover mode.
By default, the triangle is enabled.
+
+
```jsx
-
+
```
API Method:
@@ -373,28 +276,38 @@ commentElement.enablePopoverTriangleComponent();
commentElement.disablePopoverTriangleComponent();
```
-
+
+
-
-Test it out by adding a comment.
+```html
+
+```
-You should be able to leave a comment on the target element using the `Comment Tool`.
+API Method:
-
+```jsx
+const commentElement = client.getCommentElement();
+commentElement.enablePopoverTriangleComponent();
+commentElement.disablePopoverTriangleComponent();
+```
+
+
-
+## Step 6: Test Integration
-
+Test it out by opening the page with Velt components in your browser.
+Click on the Comment Tool and leave a comment on the target element.
+
-
-
+## Complete Example
-
+
+
-```jsx React / Next.js
+```jsx
import {
VeltProvider,
VeltComments,
@@ -403,86 +316,70 @@ import {
} from '@veltdev/react';
export default function App() {
-
return (
-
- {/* Comment Tool next to each element */}
+ {/* Pattern a: Comment Tool next to each element */}
-
-
+
+
+
-
-
+
+
- {/* Single Comment Tool */}
+ {/* Pattern b: Single Comment Tool */}
+
```
-
+
+
diff --git a/async-collaboration/comments/setup/tiptap.mdx b/async-collaboration/comments/setup/tiptap.mdx
index 41c73a39..65b9fea4 100644
--- a/async-collaboration/comments/setup/tiptap.mdx
+++ b/async-collaboration/comments/setup/tiptap.mdx
@@ -64,15 +64,115 @@ npm i @veltdev/tiptap-velt-comments
-#### Step 4: Add a comment button to your Tiptap editor
+#### Step 4: Add a comment button to Tiptap Bubble menu
-- Add a button that appears in the context menu of your Tiptap editor when the user selects text. Refer to the [Tiptap documentation](https://tiptap.dev/docs/editor/getting-started/style-editor/custom-menus) to learn more about custom menus.
-- This button will be used to add a comment to the selected text.
+Add a button in your existing bubble menu or create a new bubble menu that appears when users select text in the editor.
+
+
+
+ ```js
+ import { BubbleMenu, EditorContent, useEditor } from '@tiptap/react';
+ import { addComment } from '@veltdev/tiptap-velt-comments';
+
+ export default function TipTapComponent() {
+ const editor = useEditor({
+ // ... your editor configuration
+ });
+
+ const addTiptapVeltComment = () => {
+ if (editor) {
+ addComment({ editor });
+ }
+ };
+
+ return (
+
+
+
+ {/* Bubble Menu for Comments */}
+ {editor && (
+
+
+
+
+
+ )}
+
+ );
+ }
+ ```
+
+
+ ```html
+
+
+
+
+
+ ```
+
+ ```js
+ import { BubbleMenu, Editor } from '@tiptap/core';
+ import { addComment } from '@veltdev/tiptap-velt-comments';
+
+ const editor = new Editor({
+ element: document.querySelector('#editor'),
+ // ... your editor configuration
+ });
+
+ const addTiptapVeltComment = () => {
+ if (editor) {
+ addComment({ editor });
+ }
+ };
+
+ // Create bubble menu
+ const bubbleMenu = new BubbleMenu({
+ editor,
+ element: document.querySelector('.bubble-menu'),
+ tippyOptions: { duration: 100 },
+ });
+
+ // Add click handler to comment button
+ document.querySelector('.comment-button').addEventListener('click', (e) => {
+ e.preventDefault();
+ e.stopPropagation();
+ addTiptapVeltComment();
+ });
+ ```
+
+
+
+
+Refer to the [Tiptap BubbleMenu documentation](https://tiptap.dev/docs/editor/extensions/functionality/bubble-menu) to learn more about customizing the bubble menu behavior.
+
#### Step 5: Call `addComment` to add a comment
- Call this method to add a comment to selected text in the Tiptap editor. You can use this when the user clicks on the comment button in context menu or presses a keyboard shortcut.
-- Params: `AddCommentRequest`. It has the following properties:
+- Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-1). It has the following properties:
- `editor`: instance of the Tiptap editor.
- `editorId`: Id of the tiptap editor. Use this if you have multiple tiptap editors on the same page in your app. (optional)
- `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
@@ -115,7 +215,7 @@ npm i @veltdev/tiptap-velt-comments
#### Step 6: Render Comments in Tiptap Editor
- Get the comment data from Velt SDK and render it in the Tiptap Editor.
-- Params: `RenderCommentsRequest`. It has the following properties:
+- Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-1). It has the following properties:
- `editor`: Instance of the Tiptap editor.
- `editorId`: Id of the tiptap editor. Use this if you have multiple tiptap editors on the same page in your app. (optional)
- `commentAnnotations`: Array of Comment Annotation objects.
diff --git a/docs.json b/docs.json
index ca062cc2..fb44da01 100644
--- a/docs.json
+++ b/docs.json
@@ -259,6 +259,7 @@
{
"group": "Miscellaneous",
"pages": [
+ "migration/environments",
"migration/migrate-from-cord-to-velt",
"migration/migrate-from-liveblocks-to-velt",
{
diff --git a/migration/environments.mdx b/migration/environments.mdx
new file mode 100644
index 00000000..e605b2ab
--- /dev/null
+++ b/migration/environments.mdx
@@ -0,0 +1,55 @@
+---
+title: "Managing Different Environments"
+description: "Manage production, staging, and development environments with Velt API keys"
+---
+
+Each API key in Velt represents a separate environment with completely isolated data and settings.
+
+## Environment types
+
+### Production
+
+When you upgrade to a production plan, you receive a production API key.
+
+#### Setup in 4 quick steps
+
+##### **1. Upgrade your plan**
+
+Select a production plan in the Velt Console. A production API key is generated automatically.
+
+##### **2. Configure production environment**
+
+Manually replicate your staging configurations:
+- Feature settings
+- UI customization
+- Webhooks
+- Permissions
+
+##### **3. Update your application**
+
+Replace the development API key with your production API key in all locations.
+
+
+Update environment variables, config files, and any hardcoded references.
+
+
+##### **4. Test**
+
+Verify all features work with the production API key before going live.
+
+#### **Regional keys (Enterprise only)**
+
+Enterprise customers can create production API keys for specific regions to reduce latency and meet data residency requirements. See [Supported Regions](/security/supported-regions) for all available regions.
+
+Example use cases:
+- North America key for US/Canadian users
+- EU key for GDPR compliance
+- Additional regional keys as needed
+
+### Staging and development
+
+Create up to **10 API keys** for non-production environments. Use these for:
+- Staging environments per team or feature
+- Individual developer environments
+- Testing and QA
+
diff --git a/realtime-collaboration/crdt/setup/tiptap.mdx b/realtime-collaboration/crdt/setup/tiptap.mdx
index dfcabf98..74b3c04f 100644
--- a/realtime-collaboration/crdt/setup/tiptap.mdx
+++ b/realtime-collaboration/crdt/setup/tiptap.mdx
@@ -77,6 +77,10 @@ return ;
- Editor not loading: Confirm the Velt client is initialized and the API key is valid.
- Desynced content: Make sure Tiptap `history` is disabled when using collaboration.
+
+Enable browser console warnings to see detailed debugging information. The Velt SDK logs helpful warnings and errors to the console that can help you troubleshoot issues quickly.
+
+
## Complete Example