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: 
npm install @veltdev/react
# Optional: npm install --save-dev @veltdev/types

​
Step 2: Get Your API Key

  1. Go to console.velt.dev and create an account
  2. 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:
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 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.
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: 'john.doe@example.com',
  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.
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>
);

​
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.
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>
  );
}

​
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.
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>

​
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:
  1. Click the VeltCommentTool button, then hover over any element on the page to leave a comment
  2. Click the VeltCommentTool button, then draw a box on the page to leave a comment
  3. Try highlighting any text to leave a comment
  4. Test replying to comments and using the comments tool
To test presence functionality:
  1. Open two browser tabs side by side with one in incognito mode
  2. Log in with different users in each tab
  3. 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

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>
  );
}

​
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.