velt-notifications-best-practices_skill

Overview

This skill documents Velt Notifications implementation patterns and best practices for React, Next.js, and web applications. It prioritizes 12 rules across 8 categories to guide reliable in-app notifications, panels, email delivery, webhooks, and user preference management. Follow these guidelines to reduce integration errors and ensure consistent UX and delivery behavior.

How this skill works

The guidance inspects key integration areas: core setup, notification panel configuration, data access methods, settings management, triggers, delivery channels, UI customization, and debugging. Each rule explains why it matters, shows common mistakes, and provides corrected code patterns for hooks, REST endpoints, SendGrid email, webhook handling, and panel behavior. Use the rules as a checklist when implementing or auditing notification flows.

When to use it

• Adding in-app notifications or a notification panel to a React/Next.js app
• Implementing VeltNotificationsTool or configuring panel tabs (For You, All, Documents, People)
• Accessing notification data via React hooks or server-side REST APIs
• Implementing email notifications with SendGrid or webhook delivery to external services
• Managing user notification preferences and delivery channels
• Creating custom notifications programmatically via REST API

Best practices

• Enable core notifications and register VeltNotificationsTool early in app bootstrap
• Expose notification data via hooks on the client and REST APIs on the server for predictable access patterns
• Configure panel tabs and display mode (popover vs sidebar) to match your app’s navigation and device sizes
• Respect user preference settings and offer clear channel toggles (in-app, email, webhooks)
• Use idempotent REST endpoints for triggers and webhooks to avoid duplicate notifications
• Add focused debug guidance and test cases for common issues like permission errors and delivery failures

Example use cases

• A Next.js app enabling a notification sidebar with tabs for For You, All, Documents, and People
• A React dashboard using hooks to list unread notifications and mark items as read
• Server-side job sending transactional emails via SendGrid based on Velt notification events
• An integration that posts notification payloads to external services through webhooks with retries
• An admin UI to view and update user notification channel preferences