Overview
Understand how better-push fits into your application and choose the right setup path.
better-push is an open-source TypeScript library for push and in-app notifications. It runs in your application, uses your user IDs and sessions, and stores its state in your Postgres database.
How it fits together
Postgres is authoritative for devices, notification content, preferences,
delivery attempts, jobs, and operational records. With no queue, notify()
sends inline. With a queue, it writes jobs for a worker. The client-facing API
continues to use the same routes and database in either configuration.
Choose where to start
| If you want to… | Follow this path |
|---|---|
| See the full delivery loop locally | Quickstart → Emulator |
| Integrate a specific server stack | Framework walkthroughs → Sessions |
| Add browser notifications | Web Push setup → Test on devices |
| Add native mobile notifications | Choose a provider → React Native |
| Build a notification center | Typed notifications → In-app feed → Preferences |
| Prepare a production deployment | Deployment → Async delivery → Security |
| Investigate delivery issues | CLI doctor → Studio → Retries and failures |
Supported stack
| Layer | Supported choices |
|---|---|
| Runtime | Node.js 22 or newer |
| Database | PostgreSQL through pg, Drizzle, or Prisma |
| Framework | Next.js, TanStack Start, Express, Hono, NestJS, or node:http |
| Provider | Web Push, FCM, APNs, Expo, or the local emulator |
| Queue | Inline delivery, Postgres database queue, or BullMQ |
| Cache | None, in-process memory, or Redis |
| Client | Browser, React, React Native, or Expo |
Core capabilities
- Typed and ad-hoc sends through one
notify()pipeline. - Browser and native device registration with token rotation and dead-token handling.
- Paginated in-app feed, unread state, user preferences, React hooks, and copy-in UI components.
- Optional queues, workers, retries, scheduled sends, cancellation, and digests.
- Optional caching, cross-instance realtime signals, and shared rate limits.
- Local emulator, diagnostics CLI, and an operator Studio with server-side redaction and audited actions.
Application responsibilities
better-push does not host an API or subscriber store. Your application remains responsible for:
- authenticating requests and returning the correct
userIdfrom the session resolver; - authorizing every server-side
notify()call; - managing provider credentials and deployment secrets;
- applying schema changes and setting data-retention policy;
- configuring proxy-level controls such as IP rate limits and CORS when the application architecture requires them.
See Security for the complete trust boundary and Configuration for server options and package entry points.