Velt Node SDK

Velt is an SDK to add collaborative features to your product within minutes. Example: Comments like Figma, Frame.io, Google Docs or Sheets, Recording like Loom, Huddles like Slack, and much more.

@veltdev/node is the official backend SDK for Velt. Use it to power a self-hosted Velt backend or to call Velt's REST APIs directly from any Node.js or TypeScript service.

The SDK exposes two independent backends:

| Backend | Namespace | Use case | | ---------------- | ------------------- | --------------------------------------------------------- | | Self-hosting | sdk.selfHosting.* | Store Velt data in your own MongoDB + AWS S3 | | REST API | sdk.api.* | Call Velt's REST APIs directly — no database required |

• Self-hosting (sdk.selfHosting.*) simplifies backend implementation by up to 90%. Pass your DB and storage configs to the SDK, call the relevant method with the raw request payload, and return the response directly to the client.
• REST API (sdk.api.*) provides fully-typed TypeScript request objects across all Velt REST services, returning raw Velt API responses. No database or AWS configuration needed.

Features

With Velt you can add powerful collaboration features to your backend extremely fast:

• Comments like Figma, Frame.io, Google Docs, Sheets and more
• Recording like Loom (audio, video, screen)
• In-app and off-app notifications
• @mentions and assignment
• Presence, Cursors, Live Selection
• Live state sync and multiplayer editing with conflict resolution (CRDT)
• Activities, reactions, access control, and GDPR data tooling
• Workspace, API key, domain, and webhook management
• ... and so much more

Installation

npm install @veltdev/node

For the self-hosting backend, also install the optional peer dependencies you plan to use:

npm install mongodb              # required for the self-hosting backend
npm install @aws-sdk/client-s3   # required only if using S3 for attachments

Requirements

• Node.js 18+
• TypeScript 5.x (optional — JavaScript is fully supported)
• MongoDB 6+ (Percona Server or MongoDB Atlas) for self-hosting
• mongodb ^6 and @aws-sdk/client-s3 ^3 as optional peer dependencies

Quick Start

Initialize the SDK

Self-hosting (MongoDB + optional AWS):

import { VeltSDK } from '@veltdev/node';

const sdk = VeltSDK.initialize({
  database: {
    host: 'localhost:27017',
    username: 'your-username',
    password: 'your-password',
    auth_database: 'admin',
    database_name: 'velt-integration',
  },
  apiKey: 'YOUR_VELT_API_KEY',       // or set VELT_API_KEY
  authToken: 'YOUR_VELT_AUTH_TOKEN', // or set VELT_AUTH_TOKEN
});

REST API only (no database needed):

import { VeltSDK } from '@veltdev/node';

const sdk = VeltSDK.initialize({
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN',
});

// All sdk.api.* services are now available
const result = await sdk.api.organizations.getOrganizations({
  organizationIds: ['org-123'],
});

Self-hosting example

Each self-hosting service is loaded asynchronously on first access and cached afterward:

const comments = await sdk.selfHosting.getComments();

const result = await comments.getComments({
  organizationId: 'org-123',
  documentIds: ['doc-1'],
});

REST API example

Each sdk.api.* method takes a single typed request object — pass plain object literals, no class instantiation required:

await sdk.api.commentAnnotations.addCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  commentAnnotations: [{
    location: { id: 'section-1', locationName: 'Introduction' },
    commentData: [{
      commentText: 'This needs review',
      from: { userId: 'user-1', name: 'John Doe', email: '[email protected]' },
    }],
  }],
});

Shutdown

Call await sdk.close() during graceful shutdown to release the database connection pool:

await sdk.close();

Documentation

• Read the Node SDK documentation for the full setup guide, configuration reference, and a complete list of sdk.selfHosting.* and sdk.api.* methods with request/response examples.
• Browse the broader Velt documentation for guides and frontend SDK references.

Use cases

• Explore use cases to learn how collaboration could look on your product.
• Figma Template: visualize what collaboration features could look like on your product.

Releases

• See the latest changes.

Security

• Velt is SOC2 Type 2 and HIPAA compliant. Learn more

Community

• X: updates, announcements, and general Velt tips.
• Discord: ask questions and share tips.

License

MIT

Support

For issues and questions, contact [email protected] or visit docs.velt.dev.