Notifications

Upstream overview

From the upstream package documentation.

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

Use cases

From the upstream package documentation.

How it works

From the upstream package documentation.

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;

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, // Used when querying without pagination.
  batchChunkSize: 100, // Page size when querying with pagination.
  kinds: {
    // These can be configured to your needs
    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()),
    }),
  },
});

Expose App-Facing Functions with your own auth resolution:

// 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;

Create notifications from the backend:

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