velt-notifications-best-practices

Velt Notifications Best Practices

Comprehensive implementation guide for Velt's notification system in React and Next.js applications. Contains 18 rules across 10 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	Configuration	MEDIUM	config-
6	Notification Triggers	MEDIUM	triggers-
7	Delivery Channels	MEDIUM	delivery-
8	UI Customization	MEDIUM	ui-
9	Wireframe Variables	MEDIUM	wireframe-variables-
10	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. Configuration (MEDIUM)

• config-cross-organization — Cross-organization notifications: enableCrossOrganization/disableCrossOrganization, CrossOrganizationConfig (organizationIds, excludeOrganizationIds), "For You" feed merging, getCrossOrganizationConfig$() subscription

6. Notification Triggers (MEDIUM)

• triggers-custom — Create custom notifications via REST API

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

8. UI Customization (MEDIUM)

• ui-wireframes — Customize notification components with wireframes

9. 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)

10. 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