Hype StackHypeStack

Notifications

In-app notifications with live WebSocket push, a header inbox, and admin broadcast campaigns. This is the pack-notifications pack.

No special integration needed

Notifications run on the base services: Postgres for the records and the app's WebSocket connection for live push. There is no third-party account to create and no pack-specific environment variable. RESEND_API_KEY from the base template is only used by admin campaigns that email specific users.

What it depends on

  • A starter pack for auth and organizations. The inbox also lists pending organization invitations, so the pack requires the invitations capability. All three starters provide it; on the free one the invitation list stays empty.

What you get

  • A header inbox dropdown with an unread badge that updates live, in whichever layout you installed.
  • A /notifications page: mark read, mark all read, archive, and invitations you can accept or decline.
  • The same list on mobile. It loads over HTTP and refreshes when you open the screen; it does not listen for live pushes.
  • An admin Notifications section to compose broadcasts, see each campaign, and an engagement row on the dashboard.

Send a notification from your feature

One call writes the row and pushes it to the user's open tabs:

ts
import { sendNotification } from "@backend/features/notifications/modules/send-notification";

await sendNotification({
  userId: assignee.id,
  organizationId,
  actorId: user.id,
  type: "invoice.overdue",
  title: "Invoice #1042 is overdue",
  body: "Acme Corp is 7 days past the due date.",
  resourceType: "invoice",
  resourceId: invoice.id,
});
FieldRequiredWhat it does
userIdyesWho receives it. One user per call
typeyesA dotted string like invoice.overdue. The prefix picks the icon (below)
titleyesThe line people read
body-A second line. Defaults to empty
organizationId-Shows it only while that org is active. Leave it out for a notification that follows the user everywhere
actorId-Who caused it
resourceType, resourceId-What it is about. Stored, but the inbox does not read them yet
metadata-Any JSON you want stored with it
channels-Defaults to ["app"]. See the note on email below

It returns the stored record. Call it after your own write commits, the same as any socket push, so a rolled-back change never notifies anyone.

To notify several people, loop over them. There is no batch helper for feature code:

ts
await Promise.all(memberIds.map((userId) => sendNotification({ userId, organizationId, type, title })));

Things it does not do yet

  • Email. channels: ["email"] is stored on the row, but only the app channel is registered, so no email goes out. Send email yourself with resend.emails.send(...) (see Mailing), or register an email channel next to appChannel in features/notifications/channels/.
  • Links. Items in the inbox do not open the thing they are about. resourceType and resourceId are saved so you can add that in NotificationItem.
  • A live badge count from the server. The notification/count event is declared but never sent. The web badge refreshes by calling POST /notifications/sync whenever a notification/new event arrives.

Icons

getNotificationIcon picks an icon from the start of type:

Type starts withIcon
inviteUserPlus
mentionAtSign
projectFolderPlus
memberUsers
anything elseBell

Add a branch there when your feature wants its own icon.

Who can see what

  • A user sees only their own notifications, and only those for the active organization plus the ones sent without an organizationId.
  • The /notifications API has no permission check beyond being signed in, because every query is filtered to the caller's own user id.
  • Admin campaigns are sent from the admin app. Any platform admin can send them, not only super admins.

Admin campaigns

A campaign goes to one of three audiences:

AudienceHow it is delivered
EveryoneStored once. Each user gets their copy the next time their app calls POST /notifications/sync
One orgSame, limited to that organization's members
Picked usersA row per user right away, pushed live, and emailed too if you tick email

Email is only offered for picked users, so a broadcast to everyone never sends thousands of emails by accident.

Data model

ModelTableWhat it holds
NotificationnotificationOne row per user per notification. Archiving sets archivedAt, it never deletes
NotificationCampaignnotification_campaignAn admin broadcast: audience, channels, recipient and email counts, status

A user gets at most one copy of each campaign (@@unique([campaignId, userId])).

API and events

RouteWhat it does
GET /notificationsPaginated list, filter by all, unread, read
GET /notifications/unread-count{ unreadCount }
POST /notifications/syncDelivers pending broadcasts, returns the count
PATCH /notifications/:id/mark-readMark one read
POST /notifications/read-allMark all read in the active org
DELETE /notifications/:idArchive one
/admin/notifications/*Campaigns and stats, platform admins only

The socket event notification/new carries the full record. On the client, listen with useListener(socketSdk.notification.new.$listener).

Environment variables

None. RESEND_API_KEY from the base template is only needed for admin campaigns that email picked users.

After installing

Run pnpm prisma generate and then pnpm prisma migrate dev in your backend app to create the notification and notification_campaign tables.