# velt-node-sdk-best-practices

> Claude/Codex skill by [@velt-js](https://omgskills.com/library/velt-js/index.md) · 0 stars · Updated 2026-06-24

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

```sh
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-practices
```

## From 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.

## Links

- HTML page: https://omgskills.com/library/velt-js/velt-plugin-cursor/skills/velt-node-sdk-best-practices/
- GitHub: https://github.com/velt-js/velt-plugin-cursor
- Author: [@velt-js](https://omgskills.com/library/velt-js/index.md)

## More from this repo

- [install-velt](https://omgskills.com/library/velt-js/velt-plugin-cursor/skills/install-velt/index.md) — Full guided installation of the Velt collaboration SDK into a React or Next.js project.
   - [@velt-js](https://omgskills.com/library/velt-js/index.md) · 0 stars
- [velt-activity-best-practices](https://omgskills.com/library/velt-js/velt-plugin-cursor/skills/velt-activity-best-practices/index.md) — Velt Activity Logs implementation patterns and best practices for React, Next.js, and web applications.
   - [@velt-js](https://omgskills.com/library/velt-js/index.md) · 0 stars
- [velt-approval-engine-best-practices](https://omgskills.com/library/velt-js/velt-plugin-cursor/skills/velt-approval-engine-best-practices/index.md) — Best practices for the Velt Approval Engine — the declarative workflow runtime for multi-step agent + human approval...
   - [@velt-js](https://omgskills.com/library/velt-js/index.md) · 0 stars