Notifications

@halostack/notifications is the monorepo's notification engine. It can reach users through three channels — email (Resend or nodemailer, rendered with react-email), web push, and in-app messages persisted to @halostack/db — all fronted by a single dispatcher that honors each user's per-channel preferences. Application code asks the dispatcher to send a notification; the dispatcher decides which channels are eligible and routes accordingly.

Importing

The package exposes a few subpaths, each scoped to a different need. Import the narrowest one that does the job.

The ./email subpath is deliberately db-free. That lets @halostack/auth (and the test preload's mock.module) import the transactional senders without pulling the database into scope.

Structure

The codebase splits along channels and notification kinds:

• src/dispatcher.ts, src/channels.ts, and the per-channel channel-email.ts / channel-web-push.ts / channel-in-app.ts files carry the routing and delivery logic.
• src/kinds.ts and the kind-*.ts files define the notification kinds, each with a typed payload.
• src/preferences.ts holds the per-user opt-in / opt-out matrix.
• src/email/ contains transactional.ts, render.ts, and transport.ts, alongside the templates/ directory of react-email .tsx files, shared components/, and a theme.ts.

Conventions

A few things worth knowing before you extend the package:

• This package's tsconfig enables JSX, because it renders react-email on the server.
• You can preview the email templates locally with bun run --filter @halostack/notifications dev:email, which serves them on port 3333.
• Validate notification payloads with Zod, and read all transport configuration through @halostack/env rather than process.env.