Agent-Skills.md

Agent Skills: Velt 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.

UncategorizedID: velt-js/agent-skills/velt-notifications-best-practices

Repository

velt-js/agent-skills
velt-js

Install this agent skill to your local

pnpm dlx add-skill https://github.com/velt-js/agent-skills/tree/HEAD/skills/velt-notifications-best-practices

Skill Files

Browse the full folder contents for velt-notifications-best-practices.

Download Skill

Loading file tree…

skills/velt-notifications-best-practices/SKILL.md

Skill Metadata

Name
velt-notifications-best-practices
Description
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, user notification preference management, or binding Notifications Panel / Notifications Tool wireframe slots with template variables (velt-data, velt-if, velt-class).

Velt Notifications Best Practices

Comprehensive implementation guide for Velt's notification system in React and Next.js applications. Contains 17 rules across 9 categories, prioritized by impact to guide automated code generation and integration patterns.

When to Apply

Reference these guidelines when:

  • Adding in-app notifications to a React/Next.js application
  • Setting up the VeltNotificationsTool and VeltNotificationsPanel
  • Configuring notification tabs (For You, All, Documents, People)
  • Accessing notification data via hooks or REST APIs
  • Managing user notification preferences and channels
  • Reading or writing per-user notification config via REST API (document-level or org-level)
  • Setting up email notifications with SendGrid
  • Creating custom notifications via REST API
  • Integrating with external services via webhooks
  • Configuring notification delay and batching to reduce noise

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Core Setup | CRITICAL | core- | | 2 | Panel Configuration | HIGH | panel- | | 3 | Data Access | HIGH | data- | | 4 | Settings Management | MEDIUM-HIGH | settings- | | 5 | Notification Triggers | MEDIUM | triggers- | | 6 | Delivery Channels | MEDIUM | delivery- | | 7 | UI Customization | MEDIUM | ui- | | 8 | Wireframe Variables | MEDIUM | wireframe-variables- | | 9 | Debugging & Testing | LOW-MEDIUM | debug- |

Quick Reference

1. Core Setup (CRITICAL)

  • core-setup — Enable notifications and add VeltNotificationsTool

2. Panel Configuration (HIGH)

  • panel-tabs — Configure notification panel tabs (forYou, all, documents, people)
  • panel-display — Control panel open mode (popover vs sidebar)

3. Data Access (HIGH)

  • data-hooks — Use React hooks to access notification data
  • data-rest-api — Use REST APIs for server-side notification management
  • data-notification-data-provider — Register NotificationDataProvider to route custom notification fetch and delete through your own backend; applies only to notificationSource === 'custom' notifications; pipeline order is notification → user → comment

4. Settings Management (MEDIUM-HIGH)

  • settings-channels — Configure notification delivery channels
  • settings-config-rest-api — Read and write per-user notification config at document or org level via REST API

5. Notification Triggers (MEDIUM)

  • triggers-custom — Create custom notifications via REST API

6. Delivery Channels (MEDIUM)

  • delivery-email — Set up email notifications with SendGrid
  • delivery-webhooks — Integrate with external services via webhooks
  • delivery-delay-batching — Configure opt-in server-side delay and batching pipeline

7. UI Customization (MEDIUM)

  • ui-wireframes — Customize notification components with wireframes

8. Wireframe Variables (MEDIUM)

  • wireframe-variables-notifications-panel — Bind Notifications Panel wireframe slots using template variables (tabs, settings, per-row unread, empty-state)
  • wireframe-variables-notifications-tool — Bind Notifications Tool wireframe slots using template variables (bell icon swap, unread badge, panel-open active state)

9. Debugging & Testing (LOW-MEDIUM)

  • debug-common-issues — Common issues and solutions

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-setup.md
rules/shared/panel/panel-tabs.md

Each rule file contains:

  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Source pointers to official documentation

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