home / skills / velt-js / agent-skills / velt-notifications-best-practices

velt-notifications-best-practices skill

safe

/skills/velt-notifications-best-practices

This skill helps you implement robust notification systems in React and Next.js, covering panels, delivery channels, and user preferences.

npx playbooks add skill velt-js/agent-skills --skill velt-notifications-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (18)

SKILL.md

3.1 KB

---
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, or user notification preference management.
license: MIT
metadata:
  author: velt
  version: "1.0.0"
---

# Velt Notifications Best Practices

Comprehensive implementation guide for Velt's notification system in React and Next.js applications. Contains 12 rules across 8 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
- Setting up email notifications with SendGrid
- Creating custom notifications via REST API
- Integrating with external services via webhooks

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

### 4. Settings Management (MEDIUM-HIGH)

- `settings-channels` — Configure notification delivery channels

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

### 7. UI Customization (MEDIUM)

- `ui-wireframes` — Customize notification components with wireframes

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

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

FAQ

Should I rely only on client-side hooks for notification access?

No. Use client hooks for UI and REST APIs for server-side processes, background jobs, and integrations to ensure consistent access and control.

How do I avoid duplicate emails or webhook calls?

Make trigger endpoints idempotent, store event delivery state, and implement retry/de-duplication logic with unique event IDs.