Add typed, scalable in-app notifications to Convex apps with O(1) counts, cursor pagination, bulk fan-out, and lifecycle hooks.
npm install convex-notificationA fully-configurable Convex component that provides a typed notification system for in-app messaging. It handles the storage, querying, and delivery of notifications within your Convex application.
The convex-notification component provides a complete notification inbox with typed payloads, seen/dismiss state, and O(1) badge counts. Define notification kinds with validation schemas, then use the generated API functions to create and manage notifications.
Use the enqueueBatch method to send notifications to thousands of users efficiently. The component uses Workpool for background processing and includes deduplication to prevent duplicate notifications during bulk sends.
Register lifecycle hooks like onNotificationCreated to trigger email sends or push notifications. Hooks fire after state changes and should enqueue work into external systems rather than performing expensive operations inline.
Create multiple notification APIs for different target types using makeNotificationAPI with custom resolveTargetId functions. This enables user notifications, team notifications, and project notifications with proper authorization checks.
Convex-notification supports idempotent creates using dedupeKey parameters. When creating notifications with the same dedupeKey, only one notification is stored, preventing duplicates during retries or bulk operations.
Convex-notification does not send emails or push notifications directly. Instead, use lifecycle hooks like onNotificationCreated to connect notification creation to external email services or push notification systems.
The convex-notification component maintains counts in a separate targetStats table that updates when notifications are created, marked seen, or dismissed. This provides O(1) badge counts without scanning the entire notification table.
Notification kinds define the payload structure for different notification types (like team_invite or admin_broadcast). Target types determine who receives notifications (users, teams, projects) and are handled by creating separate API wrappers with different authorization logic.
Convex-notification uses a Workpool child component for bulk notification delivery. Call enqueueBatch to queue notifications for multiple targets, and the system processes them in the background with configurable batch chunk sizes.