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
invitationscapability. 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
/notificationspage: 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:
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,
});| Field | Required | What it does |
|---|---|---|
userId | yes | Who receives it. One user per call |
type | yes | A dotted string like invoice.overdue. The prefix picks the icon (below) |
title | yes | The 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:
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 withresend.emails.send(...)(see Mailing), or register an email channel next toappChannelinfeatures/notifications/channels/. - Links. Items in the inbox do not open the thing they are about.
resourceTypeandresourceIdare saved so you can add that inNotificationItem. - A live badge count from the server. The
notification/countevent is declared but never sent. The web badge refreshes by callingPOST /notifications/syncwhenever anotification/newevent arrives.
Icons
getNotificationIcon picks an icon from the start of type:
| Type starts with | Icon |
|---|---|
invite | UserPlus |
mention | AtSign |
project | FolderPlus |
member | Users |
| anything else | Bell |
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
/notificationsAPI 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:
| Audience | How it is delivered |
|---|---|
| Everyone | Stored once. Each user gets their copy the next time their app calls POST /notifications/sync |
| One org | Same, limited to that organization's members |
| Picked users | A 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
| Model | Table | What it holds |
|---|---|---|
Notification | notification | One row per user per notification. Archiving sets archivedAt, it never deletes |
NotificationCampaign | notification_campaign | An 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
| Route | What it does |
|---|---|
GET /notifications | Paginated list, filter by all, unread, read |
GET /notifications/unread-count | { unreadCount } |
POST /notifications/sync | Delivers pending broadcasts, returns the count |
PATCH /notifications/:id/mark-read | Mark one read |
POST /notifications/read-all | Mark all read in the active org |
DELETE /notifications/:id | Archive 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.