convex-notification

Convex Notification

A Convex component for typed, scalable in-app notifications.

Convex Notification gives you a durable notification inbox with:

• typed notification kinds and payloads,
• per-target counts without table scans,
• cursor pagination,
• seen/dismiss state,
• idempotent creates,
• Workpool-backed bulk fan-out,
• lifecycle hooks for email, push, analytics, or audit workflows.

Installation

npm install convex-notification

Add the component to your app:

// convex/convex.config.ts
import { defineApp } from "convex/server";
import notification from "convex-notification/convex.config.js";

const app = defineApp();

app.use(notification);

export default app;

The default component namespace is components.notification.

Define Notification Kinds

Register the notification payloads your app supports:

// convex/notifications/client.ts
import { v } from "convex/values";
import { components } from "../_generated/api";
import { defineNotifications } from "convex-notification";

export const notifications = defineNotifications(components.notification, {
  defaultListLimit: 50,
  batchChunkSize: 100,
  kinds: {
    team_invite: v.object({
      title: v.string(),
      body: v.optional(v.string()),
      href: v.string(),
      inviteId: v.string(),
    }),
    admin_broadcast: v.object({
      title: v.string(),
      body: v.optional(v.string()),
      href: v.optional(v.string()),
    }),
  },
});

kind and data are app-defined. The component stores payloads generically, while the client wrapper gives your app type-safe create/list APIs.

Expose App-Facing Functions

Components do not own your app auth. Create app-facing functions with makeNotificationAPI and derive the trusted targetId in your app code.

// convex/notifications/api.ts
import { makeNotificationAPI } from "convex-notification/server";
import { getCurrentUserOrThrow } from "../auth";
import { notifications } from "./client";

export const userNotifications = makeNotificationAPI(notifications, {
  resolveTargetId: async (ctx) => {
    const user = await getCurrentUserOrThrow(ctx);
    return user._id;
  },
});

Export the generated Convex functions:

// convex/notifications.ts
import { userNotifications } from "./notifications/api";

export const {
  list,
  listPage,
  counts,
  unseenCount,
  markSeen,
  markAllSeen,
  dismiss,
  dismissAll,
} = userNotifications;

Your frontend calls these app functions, not the component directly.

Create Notifications

await notifications.create(ctx, {
  targetId: userId,
  kind: "team_invite",
  data: {
    title: "You were invited to a team",
    body: "Open the invite to accept it.",
    href: "/invite/abc123",
    inviteId: "abc123",
  },
  source: { type: "invite", id: "abc123" },
  dedupeKey: "invite:abc123",
});

The data object is type-checked from your registered kind.

Bulk Notifications

await notifications.enqueueBatch(ctx, {
  targetIds: userIds,
  kind: "admin_broadcast",
  dedupeKeyPrefix: `broadcast:${broadcastId}`,
  data: {
    title: "New feature available",
    body: "Try it now.",
    href: "/dashboard",
  },
});

Bulk delivery runs through a Workpool child component. In the Convex dashboard you will see both notification and notification/workpool.

User, Team, And Project Inboxes

Use one component instance for most apps, then expose different app APIs for different authorized target models.

export const teamNotifications = makeNotificationAPI(notifications, {
  targetArgs: {
    teamId: v.id("teams"),
  },
  resolveTargetId: async (ctx, args) => {
    const user = await getCurrentUserOrThrow(ctx);
    await assertUserCanAccessTeam(ctx, {
      userId: user._id,
      teamId: args.teamId,
    });
    return args.teamId;
  },
});

Rule of thumb:

• Use kind for different notification types.
• Use multiple makeNotificationAPI(...) wrappers for different authorized inbox targets.
• Use multiple component instances only for different notification systems.

Separate component instances do not share rows, counts, batches, hook registration, kind definitions, or lifecycle behavior.

Lifecycle Hooks

Lifecycle hooks are backend hooks, not click handlers. Use them for durable side effects after the component changes state.

// convex/notifications/hooks.ts
import { internal } from "../_generated/api";
import { notifications } from "./client";

export const onNotificationCreated = notifications.defineOnNotificationCreated({
  handler: async (ctx, notification) => {
    switch (notification.kind) {
      case "team_invite":
        await ctx.scheduler.runAfter(0, internal.emails.sendInviteEmail, {
          targetId: notification.targetId,
          inviteId: notification.data.inviteId,
        });
        break;
    }
  },
});

Register hooks with .withHooks(...):

// convex/notifications/client.ts
import { components, internal } from "../_generated/api";
import { defineNotifications } from "convex-notification";

export const notifications = defineNotifications(components.notification, {
  kinds: { ... },
}).withHooks({
  onNotificationCreated: internal.notifications.hooks.onNotificationCreated,
  onBatchCompleted: internal.notifications.hooks.onBatchCompleted,
});

onNotificationCreated fires once per newly created notification. During large bulk sends, this can mean many hook invocations. Hook handlers should enqueue work into another durable system, such as an email or push component, not perform expensive scans or external API calls inline.

Concepts

• targetId: opaque inbox owner ID. Usually a user, team, project, or workspace ID.
• kind: app-defined discriminator for the notification payload.
• data: app-defined Convex value associated with the kind.
• source: optional domain object reference for cleanup.
• dedupeKey: optional idempotency key.
• sequence: per-target ordering key for pagination.

Counts are maintained in a targetStats table, so badge counts are O(1). Notification lists use indexed cursor pagination instead of scanning an inbox.

Web Push And Email

This package does not send emails or browser push notifications directly. Use lifecycle hooks to connect notification creation to app-owned workflows or companion components.

License

Apache-2.0