Quickstart

Get Velt up and running in your app with comments, presence, and real-time collaboration features. You’ll install the package, configure authentication, set up documents, and see collaborative features working immediately.

The SDK will not work without proper authentication and document initialization.

Prerequisites

Package manager (npm, yarn, or pnpm)
Node.js (v14 or higher)
React 16+, Vue 2+, Angular 12+, or vanilla HTML/JS
A Velt account with an API key
Optional: TypeScript types package for better development experience

Setup

Step 1: Install Dependencies

Install the required packages:

React / Next.js
Angular
Vue.js
HTML

npm install @veltdev/react
# Optional: npm install --save-dev @veltdev/types

npm install @veltdev/client
# Optional: npm install --save-dev @veltdev/types

npm install @veltdev/client
# Optional: npm install --save-dev @veltdev/types

Use our CDN Script

<script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>

Step 2: Get Your API Key

Go to console.velt.dev and create an account
Copy your API key from the dashboard

Step 3: Safelist Your Domain

In the Velt Console, add your app’s domain to “Managed Domains” to whitelist it for development and production use.

Step 4: Initialize Velt

Initialize the SDK and render the base collaborative components. Pick your framework and:

React: wrap your app with VeltProvider and pass your API key.
Angular/Vue/HTML: call the init function with your API key to bootstrap the client.

This confirms the SDK is loaded and ready for adding features in later steps. See the tabs below for your specific implementation:

React / Next.js
Angular
Vue.js
HTML

Wrap your app with VeltProvider and pass your API key.

If using Next.js, add ‘use client’ directive at the top of files containing Velt components to ensure proper client-side rendering.

'use client'; // MAKE SURE TO INCLUDE 'use client' for Next.js implementation

import { VeltProvider } from '@veltdev/react';

export default function App() {
  return (
    <VeltProvider apiKey="YOUR_VELT_API_KEY">
      {/* Your app content */}
    </VeltProvider>
  );
}

Step 1: Add schemas: [CUSTOM_ELEMENTS_SCHEMA] to allow Angular to render Velt’s custom elements (web components).Step 2: Boot the Velt client by calling initVelt with your API key.

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule
  ],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Add this line
})
export class AppModule { }

Step 1: Register Velt’s custom elements by setting Vue.config.ignoredElements = [/velt-*/].Step 2: Boot the Velt client by calling initVelt with your API key.

import Vue from 'vue';
import App from './App.vue';

// Allow Velt elements
Vue.config.ignoredElements = [/velt-*/];

new Vue({
  render: h => h(App),
}).$mount('#app');

Call Velt.init('YOUR_VELT_API_KEY') to bootstrap the client before rendering Velt components.

<script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>
  <script>
    async function loadVelt() {
      await Velt.init("YOUR_VELT_API_KEY");
    }
  </script>

Step 5: Authenticate Users

There are two ways to authenticate in Velt. Pick one based on your needs:

Auth Provider (recommended): Configure once and Velt will fetch/refresh tokens automatically. See details in the Key Concepts.
Identify API (more personable): Call identify(user, options) directly where you need it for more control. If you use Identify, you must refresh tokens yourself, see Token Refresh.

After authenticating, you can retrieve the current user object anytime using getCurrentUser() or useCurrentUser().

Critical Authentication Requirement:

You must authenticate the user. The recommended path is configuring authProvider on VeltProvider during initialization.

During development, generateToken can be omitted; however, for production it is highly recommended to provide generateToken for basic security and seamless token refresh.

You first need to create a user object with the required user information. The user object should include the following fields: userId, organizationId, name, email, and photoUrl.

// Example user object
const user = {
  userId: 'user-123',
  organizationId: 'org-abc',
  name: 'John Doe',
  email: '[email protected]',
  photoUrl: 'https://i.pravatar.cc/300',
};

Then, you need to provide a function that generates a Velt JWT token from your backend. See the JWT Token Setup. Tokens expire after 48 hours, handle renewals as shown in Token Refresh.

Access control roles: Assign users as Editor or Viewer per resource (organization, folder, document) via your JWT token permissions or backend access APIs. Editors can write collaboration data (e.g., add/edit comments); Viewers are read-only. See: Access Control, APIs Generate Token, Add Permissions, Add/Update Users.

React / Next.js
Angular
Vue.js
HTML

return (
  <VeltProvider 
    apiKey="YOUR_VELT_API_KEY"
    authProvider={{
      user,
      retryConfig: { retryCount: 3, retryDelay: 1000 },
      generateToken: async () => {
        const token = await __generateVeltAuthTokenFromYourBackend__();
        return token;
      }
    }}
  >
    {/* Your app content */}
  </VeltProvider>
);

Velt.setVeltAuthProvider({
  user,
  retryConfig: { retryCount: 3, retryDelay: 1000 },
  generateToken: async () => {
    const token = await __generateVeltAuthTokenFromYourBackend__();
    return token;
  }
});

Velt.setVeltAuthProvider({
  user,
  retryConfig: { retryCount: 3, retryDelay: 1000 },
  generateToken: async () => {
    const token = await __generateVeltAuthTokenFromYourBackend__();
    return token;
  }
});

<script>
  Velt.setVeltAuthProvider({
    user,
    retryConfig: { retryCount: 3, retryDelay: 1000 },
    generateToken: async () => {
      const token = await __generateVeltAuthTokenFromYourBackend__();
      return token;
    }
  });
</script>

Step 6: Initialize Document

A Document represents a shared collaborative space where users can interact. The setDocument method initializes this space and takes a unique documentId and optional metadata. By default, users can only access documents within their own organization. Use this to set the document for the current organization the user is logged into. Learn more about documents here. To subscribe to multiple documents in a single call, use setDocuments and pass an array; see here for more information.

The SDK will not work without initializing the document.

React / Next.js
Angular
Vue.js
HTML

import { useEffect } from 'react';
import { useVeltClient } from '@veltdev/react';

export default function DocumentComponent() {
  const { client } = useVeltClient();

  useEffect(() => {
    if (client) {
      client.setDocuments([
        { id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
      ]);
    }
  }, [client]);

  return (
    <div>
      {/* Your document content */}
    </div>
  );
}

import { Component } from '@angular/core';
import { initVelt } from '@veltdev/client';

@Component({
  selector: 'app-document',
  template: `<div><!-- Your document content --></div>`
})
export class DocumentComponent {
  client: any;

  async ngOnInit() {
    this.client = await initVelt('YOUR_VELT_API_KEY');
    // Set document for current organization
    this.client.setDocuments([
      { id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
    ]);
  }
}

import { initVelt } from '@veltdev/client';

export default {
  name: 'DocumentComponent',
  data() {
    return {
      client: null
    }
  },
  async mounted() {
    this.client = await initVelt('YOUR_VELT_API_KEY');
    // Set document for current organization
    this.client.setDocuments([
      { id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
    ]);
  }
}

// In your script tag
async function loadVelt() {
  await Velt.init("YOUR_VELT_API_KEY");

  // Set document for current organization
  Velt.setDocuments([
    { id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
  ]);
}

Step 7: Install Velt Feature Components

Add the VeltComments, VeltCommentTool, and VeltPresence components to enable comments and presence features. Use the tabs below to see the setup for React, Angular, Vue, and HTML.

React / Next.js
Angular
Vue.js
HTML

Render the comments surface at the app root; render presence and the comment tool within the document view:

import { VeltProvider, VeltComments } from '@veltdev/react';

<VeltProvider apiKey="YOUR_API_KEY">
  <VeltComments/>
  <YourAuthComponent/>
  <YourDocument/>
</VeltProvider>

Render the comments surface in the root template; render presence and the comment tool in the document component template:

<velt-comments></velt-comments>
<!-- Your other components -->

Render the comments surface in App.vue; render presence and the comment tool in your document component:

<template>
  <div id="app">
    <velt-comments></velt-comments>
    <!-- Your other components -->
  </div>
</template>

In your root component add these features (tags inside <body>):

index.html

<body>
  <h1>My Collaborative App</h1>
  <velt-comments></velt-comments>
  <velt-presence></velt-presence>
  <velt-comment-tool></velt-comment-tool>
  <!-- Your app content -->
</body>

Step 8: Verify Setup

A good first step is to check if the Velt SDK has been initialized correctly. Open your browser’s developer console and run the following command:

await Velt.getMetadata()

This should return the document metadata you’ve set. If it returns an error or null, check the console for any initialization errors. To test comments functionality:

Click the VeltCommentTool button, then hover over any element on the page to leave a comment
Click the VeltCommentTool button, then draw a box on the page to leave a comment
Try highlighting any text to leave a comment
Test replying to comments and using the comments tool

To test presence functionality:

Open two browser tabs side by side with one in incognito mode
Log in with different users in each tab
You should see user avatars appear showing presence in both tabs

If you don’t see the comments tool, check your browser console for API key or network errors.

Debugging

Common issues:

Invalid API key or domain not whitelisted: Verify your API key and ensure your domain is added under “Managed Domains” in the Velt Console
Component not rendering: Ensure the VeltProvider/script loads before your components
No collaborative features: Verify that both authentication and document initialization are properly set up
Users can’t see each other: Ensure both users are in the same organization and document
Package not found: Clear npm cache and reinstall (npm cache clean --force)
TypeScript errors: Install the optional types package (@veltdev/types)

Notes

API Key Required: Always use a valid API key from the Velt Console
Framework Compatibility: Ensure your framework version meets the minimum requirements
Child Components: Call authentication and document setup methods in child components, never in the same file as your VeltProvider
Next.js ‘use client’: Add 'use client' directive at the top of files containing Velt components for proper client-side rendering
Organization ID: Always include the organizationId when identifying users - this is required for proper access control
Document Required: The SDK will not work without calling setDocument() - this defines the collaborative space
@mention Support: To enable @mention functionality, set up user contacts here
Location Support: For organizing users within documents, learn about Locations here
TypeScript Support: Install the optional types package for better development experience

Complete Example

React / Next.js
Angular
Vue.js
HTML

If using Next.js, add ‘use client’ directive at the top of files containing Velt components to ensure proper client-side rendering.

import { VeltProvider, VeltComments } from '@veltdev/react';
import AuthComponent from './AuthComponent';
import DocumentComponent from './DocumentComponent';

export default function App() {
  return (
    <VeltProvider apiKey="YOUR_VELT_API_KEY">
      <VeltComments />
      <AuthComponent />
      <DocumentComponent />
    </VeltProvider>
  );
}

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule
  ],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Add this line
})
export class AppModule { }

import Vue from 'vue';
import App from './App.vue';

// Allow Velt elements
Vue.config.ignoredElements = [/velt-*/];

new Vue({
  render: h => h(App),
}).$mount('#app');

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Collaborative App</title>
  <script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>
  <script>
    async function loadVelt() {
      await Velt.init("YOUR_VELT_API_KEY");

      // Authenticate user
      const user = {
        userId: "user123",
        organizationId: "org123",
        name: "John Doe",
        email: "[email protected]",
        photoUrl: "https://i.pravatar.cc/300",
        color: "#FF6B6B",
        textColor: "#FFFFFF"
      };
      await Velt.identify(user);

      // Set document
      await Velt.setDocument('my-document-id', { documentName: 'My Document' });
    }
  </script>
</head>
<body>
  <h1>My Collaborative App</h1>
  <velt-comments></velt-comments>
  <velt-presence></velt-presence>
  <velt-comment-tool></velt-comment-tool>
  <!-- Your app content -->
</body>
</html>

Next Steps

Now that you’ve completed the basic setup, you can explore more advanced Velt features and concepts:

Key Concepts: For new developers we recommend reading through our curated list for an in-depth breakdown of the Velt SDK and cool features.
Documents and Locations: Learn how to structure your app’s collaborative spaces.
Users and User Groups: Configure and manage your users and groups.
Access Control: Define permissions to control who can access what.
Authentication: Explore more advanced authentication methods.
UI Customization: Customize layouts, styling, templates, and actions for Velt components.

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

Prerequisites

Setup

Step 1: Install Dependencies

Step 2: Get Your API Key

Step 3: Safelist Your Domain

Step 4: Initialize Velt

Step 5: Authenticate Users

Step 6: Initialize Document

Step 7: Install Velt Feature Components

Step 8: Verify Setup

Debugging

Notes

Complete Example

Next Steps

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

​Prerequisites

​Setup

​Step 1: Install Dependencies

​Step 2: Get Your API Key

​Step 3: Safelist Your Domain

​Step 4: Initialize Velt

​Step 5: Authenticate Users

​Step 6: Initialize Document

​Step 7: Install Velt Feature Components

​Step 8: Verify Setup

​Debugging

​Notes

​Complete Example

​Next Steps

Prerequisites

Setup

Step 1: Install Dependencies

Step 2: Get Your API Key

Step 3: Safelist Your Domain

Step 4: Initialize Velt

Step 5: Authenticate Users

Step 6: Initialize Document

Step 7: Install Velt Feature Components

Step 8: Verify Setup

Debugging

Notes

Complete Example

Next Steps