From 57b9522d3853e10b73af25c3164cfce5afca2534 Mon Sep 17 00:00:00 2001 From: yoen-velt Date: Tue, 28 Oct 2025 01:07:58 -0400 Subject: [PATCH 1/7] Added Environment docs --- docs.json | 1 + migration/environments.mdx | 170 +++++++++++++++++++++++++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 migration/environments.mdx 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..f732e17a --- /dev/null +++ b/migration/environments.mdx @@ -0,0 +1,170 @@ +--- +title: "Managing Different Environments" +description: "Learn how to manage production, staging, and development environments with Velt API keys" +--- + +Velt provides robust environment management capabilities to help you separate your production, staging, and development workflows while maintaining complete data isolation and independent configurations. + +## Environment separation + +Each environment in Velt is completely isolated through API keys. This ensures that your production data never mixes with staging or development data, and allows you to configure each environment independently based on your specific needs. + +### Production environments + + +When you upgrade your account to production, you automatically receive a new production API key. + + +Upon upgrading to a production plan, Velt automatically generates a dedicated production API key for you. This key is separate from your development keys and comes with production-level features and support. + +#### Regional API keys for enterprise + + +Enterprise customers can create multiple production API keys for different geographic regions to optimize performance and comply with data residency requirements. + + +Enterprise customers have the flexibility to create separate production API keys for different regions, such as: + +- **North America (NA)** - For US and Canadian users +- **European Union (EU)** - For EU-based users with GDPR compliance requirements +- **Other regions** - Based on your specific geographic needs + +This regional separation helps you: +- Reduce latency by serving users from geographically closer servers +- Meet data residency and compliance requirements +- Optimize performance for distributed teams + +### Staging and development environments + +For staging and development purposes, you can create up to **10 API keys** per account. This allows you to: + +- Set up multiple staging environments for different features or teams +- Create separate development environments for each developer +- Test different configurations without affecting production +- Run parallel testing scenarios + + +Each API key has a limit of 10 keys for non-production environments. Plan your environment structure accordingly. + + +## Complete environment isolation + +Every aspect of your Velt configuration is isolated by API key, ensuring complete separation between environments: + +### Isolated by API key + +Each environment maintains its own: + +- **Data** - Comments, annotations, recordings, and all collaboration data +- **Configurations** - Feature settings, UI customization, and behavior preferences +- **Webhooks** - Webhook endpoints and event subscriptions +- **Users** - User records and authentication settings +- **Permissions** - Access control rules and user groups +- **Settings** - All workspace and feature-specific settings + + +Think of each API key as a completely separate workspace with its own isolated ecosystem. + + +### Manual configuration required + + +Settings and configurations do not automatically sync between environments. You must manually configure each environment. + + +When setting up a new environment, you'll need to manually replicate: + +1. **Feature configurations** - Enable and configure features for each environment +2. **UI customization** - Apply styling and layout preferences +3. **Webhook endpoints** - Set up webhook URLs for each environment +4. **User permissions** - Define access control rules +5. **Integration settings** - Configure third-party integrations + +This manual approach ensures you have full control over what gets deployed to each environment and prevents accidental configuration changes from affecting production. + +## Best practices + +### Step 1: Plan your environment structure + +Before creating API keys, map out your environment needs: +- How many staging environments do you need? +- Do developers need individual development environments? +- Will you need region-specific production keys? + +### Step 2: Use consistent naming conventions + +Name your API keys clearly to identify their purpose: +- `production-na`, `production-eu` for regional production keys +- `staging-main`, `staging-feature-x` for different staging environments +- `dev-john`, `dev-sarah` for developer-specific environments + +### Step 3: Document your configurations + +Keep a record of critical settings for each environment to make replication easier: +- Feature flags and their states +- Custom webhook endpoints +- UI customization choices +- Permission structures + +### Step 4: Test configuration changes in staging first + +Always test significant configuration changes in staging before applying them to production: + + +Verify the changes work as expected in a safe environment before affecting your users. + + +## Creating and managing API keys + +You can create and manage your API keys through the [Velt Console](https://console.velt.dev/): + +1. Navigate to your workspace settings +2. Go to the API Keys section +3. Click "Create New API Key" +4. Provide a descriptive name for your environment +5. Select the appropriate environment type (production, staging, or development) + + +Store your API keys securely using environment variables or a secrets management service. Never commit API keys to version control. + + +## Upgrading from development to production + +When you're ready to move from development to production: + +### Step 1: Upgrade your plan + +Choose the production plan that fits your needs in the Velt Console. + + +Your new production API key will be automatically generated upon upgrade. + + +### Step 2: Manually configure your production environment + +Replicate the configurations from your staging environment: +- Feature settings +- UI customization +- Webhook endpoints +- User permissions + +### Step 3: Update your application + +Replace the development API key in your production application with the new production API key. + + +Ensure you update all instances where the API key is used, including environment variables and configuration files. + + +### Step 4: Test thoroughly + +Verify that all features work correctly with the production API key before directing user traffic. + + +Your production environment is now live and isolated from development/staging environments. + + +## Need help? + +If you need assistance with environment management or have questions about your specific use case, contact our support team through the [Velt Console](https://console.velt.dev/) or reach out via [Intercom](https://www.intercom.com/). + From cf6ccf0bda528a9610a63aa94002f8280201a0dd Mon Sep 17 00:00:00 2001 From: yoen-velt Date: Tue, 28 Oct 2025 01:23:28 -0400 Subject: [PATCH 2/7] Updated tiptap --- async-collaboration/comments/setup/tiptap.mdx | 91 ++++++++++++++++++- realtime-collaboration/crdt/setup/tiptap.mdx | 4 + 2 files changed, 91 insertions(+), 4 deletions(-) diff --git a/async-collaboration/comments/setup/tiptap.mdx b/async-collaboration/comments/setup/tiptap.mdx index 41c73a39..7a137382 100644 --- a/async-collaboration/comments/setup/tiptap.mdx +++ b/async-collaboration/comments/setup/tiptap.mdx @@ -32,7 +32,7 @@ title: "Tiptap Setup" #### Step 2: Install the Velt Tiptap extension ```bash -npm i @veltdev/tiptap-velt-comments +npm i @veltdev/tiptap-velt-comments @tiptap/react @tiptap/starter-kit ``` #### Step 3: Import and add the extension to your Tiptap editor @@ -64,10 +64,93 @@ npm i @veltdev/tiptap-velt-comments -#### Step 4: Add a comment button to your Tiptap editor +#### Step 4: Add a comment bubble menu to your Tiptap editor -- 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 bubble menu that appears when users select text in the editor. This menu will contain a button to add comments to the selected text. + + + + ```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 && ( + +
+ +
+ + )} +
+ ); + } + ``` + + + ```js + import { BubbleMenu, Editor } from '@tiptap/core'; + import { addComment } from '@veltdev/tiptap-velt-comments'; + + const editor = new 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 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 From a1a4b60ada6023cfc67d9a15875dd003edd9c4a3 Mon Sep 17 00:00:00 2001 From: yoen-velt Date: Wed, 29 Oct 2025 01:29:43 -0400 Subject: [PATCH 3/7] Updated popover comments --- .../comments/setup/popover.mdx | 67 ++++++------------- 1 file changed, 22 insertions(+), 45 deletions(-) diff --git a/async-collaboration/comments/setup/popover.mdx b/async-collaboration/comments/setup/popover.mdx index 0c4a4a4f..e0c1012f 100644 --- a/async-collaboration/comments/setup/popover.mdx +++ b/async-collaboration/comments/setup/popover.mdx @@ -8,9 +8,8 @@ title: "Popover Setup" - +## Step 1: Import Comment components - Import the `VeltComments`, `VeltCommentTool`, and `VeltCommentBubble` components. ```js @@ -22,9 +21,7 @@ import { } from '@veltdev/react'; ``` - - - +## Step 2: Add Comments component with Popover mode Add the `VeltComments` component to the root of your app and mark the `popoverMode` property as `true`. @@ -37,9 +34,8 @@ Popover mode means that comments can be attached to specific target elements. Th ``` - - +## 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 @@ -101,9 +97,8 @@ If you don't add the `data-velt-target-comment-element-id` attribute, you will b ``` - +## 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 @@ -123,9 +118,8 @@ There are two ways to add metadata to the comment: ### b. Using Comment Add Event Callback You can learn more about it [here](/async-collaboration/comments/customize-behavior#addcontext). - +## Step 5: Add the Comment Bubble component (optional) - ![](/images/popover-bubble.png) @@ -164,10 +158,8 @@ The Comment Bubble component: ``` - - - +## Step 6: Remove Popover Mode Triangle (optional) ![](/images/popover-comment-pin.png) @@ -187,29 +179,20 @@ commentElement.enablePopoverTriangleComponent(); commentElement.disablePopoverTriangleComponent(); ``` - +## Step 7: 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. ![](/images/popover-comment-pin.png) - - - - - - - - - +## Step 1: Add Comment component with Popover mode 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. @@ -219,9 +202,8 @@ This component is required to render comments in your app. ``` - - +## Step 2: 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 @@ -290,9 +272,8 @@ If you don't add the `data-velt-target-comment-element-id` attribute, you will b ``` - +## Step 3: 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 @@ -312,9 +293,8 @@ There are two ways to add metadata to the comment: ### b. Using Comment Add Event Callback You can learn more about it [here](/async-collaboration/comments/customize-behavior#addcontext). - +## Step 4: Add the Comment Bubble component (optional) - ![](/images/popover-bubble.png) This component accepts a target element ID & binds the comment annotation to it. @@ -350,9 +330,8 @@ This gives you a lot of flexibility as you can place this component anywhere and ``` - - +## Step 5: Remove Popover Mode Triangle (optional) ![](/images/popover-comment-pin.png) @@ -373,26 +352,21 @@ commentElement.enablePopoverTriangleComponent(); commentElement.disablePopoverTriangleComponent(); ``` - +## Step 6: Test Integration - Test it out by adding a comment. You should be able to leave a comment on the target element using the `Comment Tool`. ![](/images/popover-comment-pin.png) - - - - - - - - +## Complete Example + + + ```jsx React / Next.js import { @@ -441,8 +415,10 @@ export default function App() { } ``` + + -```html HTML +```html @@ -485,4 +461,5 @@ export default function App() { ``` - + + From fdffc7e188a00fc52ecf2a8c465d38f10a56612d Mon Sep 17 00:00:00 2001 From: yoen-velt Date: Thu, 6 Nov 2025 15:04:27 -0500 Subject: [PATCH 4/7] Updated Env docs --- migration/environments.mdx | 194 +++++++++++++------------------------ 1 file changed, 68 insertions(+), 126 deletions(-) diff --git a/migration/environments.mdx b/migration/environments.mdx index f732e17a..fc80321c 100644 --- a/migration/environments.mdx +++ b/migration/environments.mdx @@ -1,170 +1,112 @@ --- title: "Managing Different Environments" -description: "Learn how to manage production, staging, and development environments with Velt API keys" +description: "Manage production, staging, and development environments with Velt API keys" --- -Velt provides robust environment management capabilities to help you separate your production, staging, and development workflows while maintaining complete data isolation and independent configurations. +Each API key in Velt represents a separate environment with completely isolated data and settings. -## Environment separation +## Environment types -Each environment in Velt is completely isolated through API keys. This ensures that your production data never mixes with staging or development data, and allows you to configure each environment independently based on your specific needs. +### Production -### Production environments +When you upgrade to a production plan, you receive a production API key. - -When you upgrade your account to production, you automatically receive a new production API key. - +#### Setup in 4 quick steps -Upon upgrading to a production plan, Velt automatically generates a dedicated production API key for you. This key is separate from your development keys and comes with production-level features and support. +##### **1. Upgrade your plan** -#### Regional API keys for enterprise +Select a production plan in the Velt Console. A production API key is generated automatically. - -Enterprise customers can create multiple production API keys for different geographic regions to optimize performance and comply with data residency requirements. - - -Enterprise customers have the flexibility to create separate production API keys for different regions, such as: - -- **North America (NA)** - For US and Canadian users -- **European Union (EU)** - For EU-based users with GDPR compliance requirements -- **Other regions** - Based on your specific geographic needs - -This regional separation helps you: -- Reduce latency by serving users from geographically closer servers -- Meet data residency and compliance requirements -- Optimize performance for distributed teams +##### **2. Configure production environment** -### Staging and development environments +Manually replicate your staging configurations: +- Feature settings +- UI customization +- Webhooks +- Permissions -For staging and development purposes, you can create up to **10 API keys** per account. This allows you to: +##### **3. Update your application** -- Set up multiple staging environments for different features or teams -- Create separate development environments for each developer -- Test different configurations without affecting production -- Run parallel testing scenarios +Replace the development API key with your production API key in all locations. -Each API key has a limit of 10 keys for non-production environments. Plan your environment structure accordingly. +Update environment variables, config files, and any hardcoded references. -## Complete environment isolation +##### **4. Test** + +Verify all features work with the production API key before going live. + +**Regional keys (Enterprise only)** -Every aspect of your Velt configuration is isolated by API key, ensuring complete separation between environments: +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. -### Isolated by API key +Example use cases: +- North America key for US/Canadian users +- EU key for GDPR compliance +- Additional regional keys as needed -Each environment maintains its own: +### Staging and development -- **Data** - Comments, annotations, recordings, and all collaboration data -- **Configurations** - Feature settings, UI customization, and behavior preferences -- **Webhooks** - Webhook endpoints and event subscriptions -- **Users** - User records and authentication settings -- **Permissions** - Access control rules and user groups -- **Settings** - All workspace and feature-specific settings +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 - -Think of each API key as a completely separate workspace with its own isolated ecosystem. - +## Data isolation -### Manual configuration required +Each API key has completely separate: +- Data (comments, recordings, etc.) +- Feature configurations +- Webhooks +- Users and permissions +- UI customization Settings and configurations do not automatically sync between environments. You must manually configure each environment. -When setting up a new environment, you'll need to manually replicate: - -1. **Feature configurations** - Enable and configure features for each environment -2. **UI customization** - Apply styling and layout preferences -3. **Webhook endpoints** - Set up webhook URLs for each environment -4. **User permissions** - Define access control rules -5. **Integration settings** - Configure third-party integrations - -This manual approach ensures you have full control over what gets deployed to each environment and prevents accidental configuration changes from affecting production. - -## Best practices - -### Step 1: Plan your environment structure - -Before creating API keys, map out your environment needs: -- How many staging environments do you need? -- Do developers need individual development environments? -- Will you need region-specific production keys? - -### Step 2: Use consistent naming conventions - -Name your API keys clearly to identify their purpose: -- `production-na`, `production-eu` for regional production keys -- `staging-main`, `staging-feature-x` for different staging environments -- `dev-john`, `dev-sarah` for developer-specific environments - -### Step 3: Document your configurations +## Configuration management -Keep a record of critical settings for each environment to make replication easier: -- Feature flags and their states -- Custom webhook endpoints -- UI customization choices -- Permission structures +When setting up a new environment, manually replicate these settings: -### Step 4: Test configuration changes in staging first +1. Feature configurations +2. UI customization +3. Webhook endpoints +4. User permissions +5. Integration settings -Always test significant configuration changes in staging before applying them to production: +**Naming convention** - -Verify the changes work as expected in a safe environment before affecting your users. - +Use clear names to identify each environment: +``` +production-na, production-eu +staging-main, staging-feature-x +dev-john, dev-sarah +``` -## Creating and managing API keys +**Configuration tracking** -You can create and manage your API keys through the [Velt Console](https://console.velt.dev/): - -1. Navigate to your workspace settings -2. Go to the API Keys section -3. Click "Create New API Key" -4. Provide a descriptive name for your environment -5. Select the appropriate environment type (production, staging, or development) +Document your settings per environment: +- Enabled features +- Webhook URLs +- UI customizations +- Permission rules -Store your API keys securely using environment variables or a secrets management service. Never commit API keys to version control. +Test configuration changes in staging before applying to production. -## Upgrading from development to production - -When you're ready to move from development to production: - -### Step 1: Upgrade your plan - -Choose the production plan that fits your needs in the Velt Console. +## Managing API keys - -Your new production API key will be automatically generated upon upgrade. - - -### Step 2: Manually configure your production environment - -Replicate the configurations from your staging environment: -- Feature settings -- UI customization -- Webhook endpoints -- User permissions +Create and manage keys in the [Velt Console](https://console.velt.dev/): -### Step 3: Update your application - -Replace the development API key in your production application with the new production API key. +1. Go to workspace settings +2. Open API Keys section +3. Click "Create New API Key" +4. Name your environment +5. Select environment type -Ensure you update all instances where the API key is used, including environment variables and configuration files. +Store API keys in environment variables or a secrets manager. Never commit them to version control. - -### Step 4: Test thoroughly - -Verify that all features work correctly with the production API key before directing user traffic. - - -Your production environment is now live and isolated from development/staging environments. - - -## Need help? - -If you need assistance with environment management or have questions about your specific use case, contact our support team through the [Velt Console](https://console.velt.dev/) or reach out via [Intercom](https://www.intercom.com/). - From 13a69953457da798c6086bf4145077d4ff4138cd Mon Sep 17 00:00:00 2001 From: yoen-velt Date: Thu, 6 Nov 2025 15:29:28 -0500 Subject: [PATCH 5/7] Tiptap + Popover comments cleanup --- .../comments/setup/popover.mdx | 397 +++++++----------- async-collaboration/comments/setup/tiptap.mdx | 4 +- 2 files changed, 160 insertions(+), 241 deletions(-) diff --git a/async-collaboration/comments/setup/popover.mdx b/async-collaboration/comments/setup/popover.mdx index e0c1012f..129f5730 100644 --- a/async-collaboration/comments/setup/popover.mdx +++ b/async-collaboration/comments/setup/popover.mdx @@ -4,11 +4,10 @@ title: "Popover Setup" ![](/gifs/Add-Cell-Comment.gif) +## Step 1: Import Comment components - - -## Step 1: Import Comment components + Import the `VeltComments`, `VeltCommentTool`, and `VeltCommentBubble` components. @@ -21,13 +20,22 @@ import { } from '@veltdev/react'; ``` + + + +No imports needed. The Velt SDK is loaded via script tag. + + + + ## Step 2: Add Comments component with Popover mode -Add the `VeltComments` component to the root of your app and mark the `popoverMode` property as `true`. +Add the Comments component to the root of your app and enable Popover mode. -This component is required to render comments in your app. +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). -Popover mode means that comments can be attached to specific target elements. The UX pattern is very similar to commenting in Google Sheets. + + ```js @@ -35,312 +43,242 @@ Popover mode means that comments can be attached to specific target elements. Th ``` + + + +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. -![](/images/comment-tool.png) +- 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 +![](/images/comment-tool.png) -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. ![](/images/popover-comment-show.png) + + ```jsx
- +
- +
``` + + + +```html +
+
+ +
+
+ +
+
+``` + + + + ### b. Single Comment Tool ![](/gifs/freestyle-popover.gif) -- 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 per element with this approach -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: +You can add metadata to comments 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 + + + ```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) ![](/images/popover-bubble.png) -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 +- 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
- +
- +
``` -## Step 6: Remove Popover Mode Triangle (optional) - -![](/images/popover-comment-pin.png) - -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(); -``` - -## Step 7: 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. - -![](/images/popover-comment-pin.png) - - - - - - -## Step 1: Add Comment component with Popover mode -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 - - - -``` - -## Step 2: 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 - -### 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. - -![](/images/comment-tool.png) - -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. - -![](/images/popover-comment-show.png) - + + ```html
- + + >
- + + >
``` -### Single Comment Tool - -![](/gifs/freestyle-popover.gif) - + + -If you want to have a single `Comment Tool` in a single location such as the navigation bar, you can do so as well. +## Step 6: Remove Popover Mode Triangle (optional) -To do this, add `data-velt-target-comment-element-id` as an attribute on each element you want to add comments on. +![](/images/popover-comment-pin.png) -Now, when you click on the `Comment Tool` and click on the target element, it will attach a `Popover` comment to the element. +You can remove the triangle that appears in Popover mode. -You will now notice that you can only add one `Comment Annotation` per element. +By default, the triangle is enabled. - -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 -
- -
-
- -
-
- -
-
-
+ ``` -## Step 3: 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 -- 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 +API Method: -```html - +```jsx +const commentElement = client.getCommentElement(); +commentElement.enablePopoverTriangleComponent(); +commentElement.disablePopoverTriangleComponent(); ``` -### b. Using Comment Add Event Callback -You can learn more about it [here](/async-collaboration/comments/customize-behavior#addcontext). - -## Step 4: Add the Comment Bubble component (optional) - -![](/images/popover-bubble.png) - -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 -
-
- - -
-
- - -
-
-``` - -## Step 5: Remove Popover Mode Triangle (optional) - -![](/images/popover-comment-pin.png) - -You can choose to remove the triangle that appears in `Popover` mode. - -By default, the triangle is enabled. - - -```jsx ``` @@ -352,23 +290,23 @@ commentElement.enablePopoverTriangleComponent(); commentElement.disablePopoverTriangleComponent(); ``` -## Step 6: Test Integration + + -Test it out by adding a comment. +## Step 7: Test Integration -You should be able to leave a comment on the target element using the `Comment Tool`. +Test it out by opening the page with Velt components in your browser. -![](/images/popover-comment-pin.png) +Click on the Comment Tool and leave a comment on the target element. - - +![](/images/popover-comment-pin.png) ## Complete Example -```jsx React / Next.js +```jsx import { VeltProvider, VeltComments, @@ -377,23 +315,17 @@ import { } from '@veltdev/react'; export default function App() { - return ( - {/* Comment Tool next to each element */}
- +
- +
@@ -402,14 +334,11 @@ export default function App() {
-
-
- ); } @@ -427,36 +356,26 @@ export default function App() { -
- +
- +
-
- -
-
- -
-
- -
+ +
+
+
+
+
- - ``` diff --git a/async-collaboration/comments/setup/tiptap.mdx b/async-collaboration/comments/setup/tiptap.mdx index 7a137382..8dace83e 100644 --- a/async-collaboration/comments/setup/tiptap.mdx +++ b/async-collaboration/comments/setup/tiptap.mdx @@ -64,9 +64,9 @@ npm i @veltdev/tiptap-velt-comments @tiptap/react @tiptap/starter-kit -#### Step 4: Add a comment bubble menu to your Tiptap editor +#### Step 4: Add a comment button to Tiptap Bubble menu -Add a bubble menu that appears when users select text in the editor. This menu will contain a button to add comments 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. From 56a00b588a0910d57bba9b22e3ec28b86dd74119 Mon Sep 17 00:00:00 2001 From: yoen-velt Date: Thu, 6 Nov 2025 15:40:24 -0500 Subject: [PATCH 6/7] Updated customize-behavior for comments --- .../comments/customize-behavior.mdx | 105 +++++++++++++++--- 1 file changed, 90 insertions(+), 15 deletions(-) diff --git a/async-collaboration/comments/customize-behavior.mdx b/async-collaboration/comments/customize-behavior.mdx index f2177d8b..df223955 100644 --- a/async-collaboration/comments/customize-behavior.mdx +++ b/async-collaboration/comments/customize-behavior.mdx @@ -88,30 +88,29 @@ commentElement.addCommentOnSelectedText(); ![](/images/addCommentOnElement.png) - 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: +To add a comment on a specific element through an API method, use the `addCommentOnElement()` method and pass in an object with the schema shown in the examples: + +**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", "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. }, "commentData": [ { - "commentText": "This is awesome! Well done.", // To set plain text content - "commentHtml": "This is test comment.", // To set HTML formatted content - "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with - "replaceContentHtml": "This is new comment.", // If replacement text contains html formatted text, then provide it here + "commentText": "This is awesome! Well done.", + "commentHtml": "This is test comment.", + "replaceContentText": "This is new comment", + "replaceContentHtml": "This is new comment.", } ], "status": "open", // optional (default: open) @@ -123,21 +122,21 @@ commentElement.addCommentOnElement(element); -```jsx +```jsx const element = { "targetElement": { - "elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element) + "elementId": "element_id", "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. }, "commentData": [ { - "commentText": "This is awesome! Well done.", // To set plain text content - "commentHtml": "This is test comment.", // To set HTML formatted content - "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with - "replaceContentHtml": "This is new comment.", // If replacement text contains html formatted text, then provide it here + "commentText": "This is awesome! Well done.", + "commentHtml": "This is test comment.", + "replaceContentText": "This is new comment", + "replaceContentHtml": "This is new comment.", } ], "status": "open", // optional (default: open) @@ -147,8 +146,58 @@ const commentElement = Velt.getCommentElement(); commentElement.addCommentOnElement(element); ``` + +**Example 2: Add comment with context metadata:** + + + +```jsx +const element = { + "targetElement": { + "elementId": "element_id", + }, + "commentData": [ + { + "commentText": "This is awesome! Well done.", + } + ], + "context": { + "product": "cheese", + "location": "zurich" + }, + "status": "open", +} + +const commentElement = client.getCommentElement(); +commentElement.addCommentOnElement(element); +``` + + + + +```jsx +const element = { + "targetElement": { + "elementId": "element_id", + }, + "commentData": [ + { + "commentText": "This is awesome! Well done.", + } + ], + "context": { + "product": "cheese", + "location": "zurich" + }, + "status": "open", +} + +const commentElement = Velt.getCommentElement(); +commentElement.addCommentOnElement(element); +``` + #### addManualComment @@ -2069,6 +2118,8 @@ Extra fields in the comment context don't prevent a match. { product: "cheese", category: "dairy"} ❌ No match (missing field) ``` +**Example 1: Comment Bubble with Partial Match** + ```jsx @@ -2089,6 +2140,30 @@ Extra fields in the comment context don't prevent a match. +**Example 2: Comment Tool with Partial Match** + + + +```jsx + +``` + + +```html + + +``` + + + --- ### Grouping Matched Comment Annotations From f5f9627d670c8d93a1bc148e58787d0fde1ed75c Mon Sep 17 00:00:00 2001 From: yoen-velt Date: Fri, 7 Nov 2025 16:41:36 -0500 Subject: [PATCH 7/7] Env docs with feedback applied --- .../comments/customize-behavior.mdx | 103 ++++-------------- .../comments/setup/popover.mdx | 87 +++++++-------- async-collaboration/comments/setup/tiptap.mdx | 23 +++- migration/environments.mdx | 59 +--------- 4 files changed, 87 insertions(+), 185 deletions(-) diff --git a/async-collaboration/comments/customize-behavior.mdx b/async-collaboration/comments/customize-behavior.mdx index df223955..9346d981 100644 --- a/async-collaboration/comments/customize-behavior.mdx +++ b/async-collaboration/comments/customize-behavior.mdx @@ -90,7 +90,7 @@ 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 shown in the examples: +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:** @@ -100,17 +100,17 @@ To add a comment on a specific element through an API method, use the `addCommen ```jsx const element = { "targetElement": { - "elementId": "element_id", + "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. }, "commentData": [ { - "commentText": "This is awesome! Well done.", - "commentHtml": "This is test comment.", - "replaceContentText": "This is new comment", - "replaceContentHtml": "This is new comment.", + "commentText": "This is awesome! Well done.", // To set plain text content + "commentHtml": "This is test comment.", // To set HTML formatted content + "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with + "replaceContentHtml": "This is new comment.", // If replacement text contains html formatted text, then provide it here } ], "status": "open", // optional (default: open) @@ -126,17 +126,17 @@ commentElement.addCommentOnElement(element); ```jsx const element = { "targetElement": { - "elementId": "element_id", + "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. }, "commentData": [ { - "commentText": "This is awesome! Well done.", - "commentHtml": "This is test comment.", - "replaceContentText": "This is new comment", - "replaceContentHtml": "This is new comment.", + "commentText": "This is awesome! Well done.", // To set plain text content + "commentHtml": "This is test comment.", // To set HTML formatted content + "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with + "replaceContentHtml": "This is new comment.", // If replacement text contains html formatted text, then provide it here } ], "status": "open", // optional (default: open) @@ -148,58 +148,6 @@ commentElement.addCommentOnElement(element); -**Example 2: Add comment with context metadata:** - - - - -```jsx -const element = { - "targetElement": { - "elementId": "element_id", - }, - "commentData": [ - { - "commentText": "This is awesome! Well done.", - } - ], - "context": { - "product": "cheese", - "location": "zurich" - }, - "status": "open", -} - -const commentElement = client.getCommentElement(); -commentElement.addCommentOnElement(element); -``` - - - - -```jsx -const element = { - "targetElement": { - "elementId": "element_id", - }, - "commentData": [ - { - "commentText": "This is awesome! Well done.", - } - ], - "context": { - "product": "cheese", - "location": "zurich" - }, - "status": "open", -} - -const commentElement = Velt.getCommentElement(); -commentElement.addCommentOnElement(element); -``` - - - #### addManualComment - This feature is particularly useful for complex UIs where you need precise control over the placement of Comment Pins. - Using this you can manually set the position of Comment Annotations. @@ -2118,33 +2066,18 @@ Extra fields in the comment context don't prevent a match. { product: "cheese", category: "dairy"} ❌ No match (missing field) ``` -**Example 1: Comment Bubble with Partial Match** +**Example** ```jsx +{/* Comment Bubble with Partial Match */} -``` - - -```html - - -``` - - -**Example 2: Comment Tool with Partial Match** - - - -```jsx +{/* Comment Tool with Partial Match */} ```html + + + + + - + Add the comment component to your template close to the root level of your ``. @@ -70,6 +70,7 @@ Add a Comment Tool near each cell or element you want to comment on. For example - 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) ![](/images/comment-tool.png) @@ -116,7 +117,8 @@ 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 per element with this approach +- 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. @@ -157,11 +159,10 @@ If you don't add the `data-velt-target-comment-element-id` attribute, you will b ## Step 4: Add Metadata to the Comment -You can add metadata to comments 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 +- Use the metadata later when processing notifications ### a. Using Comment Tool @@ -196,7 +197,7 @@ Either use this or the default triangle component. Using both could cause visual The Comment Bubble component: - Displays a count of replies for a comment thread -- Must have the same `targetElementId` as its associated element +- 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 @@ -252,7 +253,7 @@ The Comment Bubble component: -## Step 6: Remove Popover Mode Triangle (optional) +### Remove Popover Mode Triangle (optional) ![](/images/popover-comment-pin.png) @@ -293,7 +294,7 @@ commentElement.disablePopoverTriangleComponent(); -## Step 7: Test Integration +## Step 6: Test Integration Test it out by opening the page with Velt components in your browser. @@ -319,23 +320,26 @@ export default function App() { - {/* Comment Tool next to each element */} + {/* Pattern a: Comment Tool next to each element */}
-
- +
+ +
-
- +
+
- {/* Single Comment Tool */} + {/* Pattern b: Single Comment Tool */}
- +
-
+
+ Content
-
+
+ Content
@@ -348,36 +352,33 @@ export default function App() { ```html - - - - Comment documentation - - - - - -
-
- -
-
- -
+ + + + +
+
+ + +
+
+
+
- -
- -
-
-
-
-
+ +
+ +
+
+ Content +
+
+ Content
- - +
+ ``` diff --git a/async-collaboration/comments/setup/tiptap.mdx b/async-collaboration/comments/setup/tiptap.mdx index 8dace83e..65b9fea4 100644 --- a/async-collaboration/comments/setup/tiptap.mdx +++ b/async-collaboration/comments/setup/tiptap.mdx @@ -32,7 +32,7 @@ title: "Tiptap Setup" #### Step 2: Install the Velt Tiptap extension ```bash -npm i @veltdev/tiptap-velt-comments @tiptap/react @tiptap/starter-kit +npm i @veltdev/tiptap-velt-comments ``` #### Step 3: Import and add the extension to your Tiptap editor @@ -94,6 +94,7 @@ Add a button in your existing bubble menu or create a new bubble menu that appea
+
+ ``` + ```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 }); @@ -155,7 +172,7 @@ Refer to the [Tiptap BubbleMenu documentation](https://tiptap.dev/docs/editor/ex #### 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) @@ -198,7 +215,7 @@ Refer to the [Tiptap BubbleMenu documentation](https://tiptap.dev/docs/editor/ex #### 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/migration/environments.mdx b/migration/environments.mdx index fc80321c..e605b2ab 100644 --- a/migration/environments.mdx +++ b/migration/environments.mdx @@ -37,7 +37,7 @@ Update environment variables, config files, and any hardcoded references. Verify all features work with the production API key before going live. -**Regional keys (Enterprise only)** +#### **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. @@ -53,60 +53,3 @@ Create up to **10 API keys** for non-production environments. Use these for: - Individual developer environments - Testing and QA -## Data isolation - -Each API key has completely separate: -- Data (comments, recordings, etc.) -- Feature configurations -- Webhooks -- Users and permissions -- UI customization - - -Settings and configurations do not automatically sync between environments. You must manually configure each environment. - - -## Configuration management - -When setting up a new environment, manually replicate these settings: - -1. Feature configurations -2. UI customization -3. Webhook endpoints -4. User permissions -5. Integration settings - -**Naming convention** - -Use clear names to identify each environment: -``` -production-na, production-eu -staging-main, staging-feature-x -dev-john, dev-sarah -``` - -**Configuration tracking** - -Document your settings per environment: -- Enabled features -- Webhook URLs -- UI customizations -- Permission rules - - -Test configuration changes in staging before applying to production. - - -## Managing API keys - -Create and manage keys in the [Velt Console](https://console.velt.dev/): - -1. Go to workspace settings -2. Open API Keys section -3. Click "Create New API Key" -4. Name your environment -5. Select environment type - - -Store API keys in environment variables or a secrets manager. Never commit them to version control. -