velt-node-sdk-best-practices
Velt Node SDK (`@veltdev/node`) implementation patterns for Node.js / TypeScript backends. Use whenever the user is writing server-side code that integrates with Velt — initializing `VeltSDK`, calling `sdk.api.*` (REST API services like Organizations, Documents, Comment Annotations, etc.) or `sdk.selfHosting.*` (MongoDB+S3 self-hosted services like Comments, Reactions, Attachments), generating JWT auth tokens for the frontend SDK from Node, configuring MongoDB or AWS S3 for self-hosting, handling the SDK's typed error classes (`VeltSDKError`, `VeltDatabaseError`, `VeltValidationError`, `VeltTokenError`, `VeltApiError`), debugging response-envelope mismatches between the two backends, or shipping Node code that talks to Velt in any way. Triggers on any mention of `@veltdev/node`, `VeltSDK`, `sdk.api`, `sdk.selfHosting`, Velt server-side Node.js, MongoDB-backed Velt storage, or env-var auth (`VELT_API_KEY` / `VELT_AUTH_TOKEN`) — even if the user doesn't say "Node SDK" explicitly.
Install
With your agent
Install OMGSkills skill "velt-js/velt-plugin-cursor:skills/velt-node-sdk-best-practices" into this agent's normal skills directory: call the OMGSkills MCP get_install_plan tool for your agent and run the script it returns (it installs only the pinned commit and verifies SKILL.md), and stop if MCP or the pin is unavailable. Do not overwrite or change existing skills without asking me.
Manual command
git clone https://github.com/velt-js/velt-plugin-cursor /tmp/velt-plugin-cursor && ln -s /tmp/velt-plugin-cursor/skills/velt-node-sdk-best-practices ~/.claude/skills/velt-node-sdk-best-practicesFrom README
Velt Node SDK Best Practices Implementation guide for @veltdev/node. The SDK has two independent backends that share the same VeltSDK instance but differ in initialization requirements, lazy-load patterns, and response shapes — most bugs stem from blurring that line. When to Apply Initializing VeltSDK.initialize(...) in a Node service Calling any method under sdk.api. or sdk.selfHosting. Generating Velt auth tokens server-side (getToken) for the frontend Configuring MongoDB or AWS S3 for self-hosting Catching and discriminating SDK errors Debugging "result.success is undefined" / "is not a function" / "cannot find module mongodb" symptoms The two-backend mental model sdk.api. is a thin typed wrapper over the Velt REST API. No database needed; service instances are available synchronously after init. sdk.selfHosting. is a server-side persistence layer that requires database config; service instances are lazy-loaded via await sdk.selfHosting.getXxx() and cached.
More from this repo
install-velt
Full guided installation of the Velt collaboration SDK into a React or Next.js project.
velt-activity-best-practices
Velt Activity Logs implementation patterns and best practices for React, Next.js, and web applications.
velt-approval-engine-best-practices
Best practices for the Velt Approval Engine — the declarative workflow runtime for multi-step agent + human approval...