velt-setup-best-practices
Velt Setup Best Practices
Comprehensive setup guide for Velt collaboration SDK. Contains 24 rules across 8 categories covering installation, authentication, document setup, and project organization.
When to Apply
Reference these guidelines when:
- Setting up Velt in a new React, Next.js, Angular, Vue, or HTML project
- Configuring VeltProvider and API keys
- Implementing user authentication with Velt (userId, organizationId)
- Setting up JWT token generation for production
- Initializing documents with documentId
- Organizing Velt-related files in your project
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Installation | CRITICAL | install- |
| 2 | Provider Wiring | CRITICAL | provider- |
| 3 | Identity | CRITICAL | identity- |
| 4 | Document Identity | CRITICAL | document- |
| 5 | Config | HIGH | config- |
| 6 | Project Structure | MEDIUM | structure- |
| 7 | Routing Surfaces | MEDIUM | surface- |
| 8 | Debugging & Testing | LOW-MEDIUM | debug- |
How to Use
Read individual rule files for detailed explanations and code examples:
rules/react/installation/install-react-packages.md
rules/react/provider-wiring/provider-velt-provider-setup.md
rules/shared/_sections.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Verification checklist
- Source pointers to official docs
Compiled Documents
AGENTS.md— Compressed index of all rules with file paths (start here)AGENTS.full.md— Full verbose guide with all rules expanded inline
More from velt-js/agent-skills
velt-crdt-best-practices
Velt CRDT (Yjs) collaborative editing best practices for real-time applications. This skill should be used when implementing collaborative features using Velt CRDT stores, integrating with editors like Tiptap, BlockNote, CodeMirror, or ReactFlow, or debugging sync issues. Triggers on tasks involving real-time collaboration, multiplayer editing, CRDT stores, or Velt SDK integration.
28velt-comments-best-practices
Velt Comments implementation patterns and best practices for React, Next.js, and web applications. Use when adding collaborative commenting features, comment modes (Freestyle, Popover, Stream, Text, Page), rich text editor comments (TipTap, SlateJS, Lexical), media player comments, or chart comments.
27velt-notifications-best-practices
Velt Notifications implementation patterns and best practices for React, Next.js, and web applications. Use when adding in-app notifications, notification panels, email notifications via SendGrid, webhook integrations, or user notification preference management.
25velt-activity-best-practices
Velt Activity Logs implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time activity feeds, custom activity logging, audit trails, CRDT debounce configuration, or server-side activity management via REST API.
7velt-rest-apis-best-practices
Velt REST API v2 and webhook best practices for server-side integration. Use when calling Velt REST API v2 endpoints, generating JWT tokens for frontend authentication, handling Velt webhooks (comment events, huddle events, CRDT updates), managing users/documents/organizations via REST, or implementing server-side Velt operations. Triggers on any task involving Velt REST API, JWT token generation for Velt, Velt webhooks, x-velt-api-key headers, or server-side comment/notification/activity management — even if the user doesn't explicitly say 'REST API'. For the Python SDK (velt-py) for self-hosting, see velt-self-hosting-data-best-practices instead.
5velt-single-editor-mode-best-practices
Velt Single Editor Mode implementation patterns and best practices for React, Next.js, and web applications. Use when implementing exclusive editing access, editor/viewer role management, access request handoff flows, element-level sync control, timeout-based editor transfer, or multi-tab editing restrictions.
5