Setting Up Browser Push Notifications for Your PWA
Browser push notifications bring your PWA closer to a native app experience. This guide covers the technical setup — from generating VAPID keys to managing subscriptions in your backend.
What is the Web Push Protocol?
The Web Push Protocol is a W3C standard that allows servers to send messages to browsers even when the user isn't actively on your site. It works via a service worker — a background script that runs in the browser — which receives push events and displays notifications. The connection between your server and the browser's push service is secured using VAPID (Voluntary Application Server Identification) keys.
Generating VAPID keys
VAPID keys are a public/private key pair that identify your server to browser push services (Google, Mozilla, Apple). You only need one set per application deployment. Generate them with the web-push npm package and store them securely — the private key never leaves your server.
- Run: npx web-push generate-vapid-keys
- Store VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY as environment variables
- Expose the public key to the frontend via a VITE_ prefixed env var
- Never expose the private key to the client
Registering a service worker
Your PWA must register a service worker that listens for push events. The service worker file (typically sw.js) handles the 'push' event, parses the notification payload, and calls self.registration.showNotification(). It also handles 'notificationclick' events to open or focus the app when a notification is tapped.
Subscribing users
To subscribe a user, call pushManager.subscribe() with the server's VAPID public key and the 'push' permission. This returns a PushSubscription object containing the endpoint URL and encryption keys. Store this subscription in your backend (keyed by user ID) for later use when sending messages.
Sending push notifications from the server
When a broadcast message is sent, your backend retrieves all relevant PushSubscription objects and calls the Web Push API for each one. Use the web-push library to handle the encryption and HTTP request to the browser's push endpoint. If a subscription returns a 410 (Gone) status, remove it from your database — the user has revoked permission.
Handling notification preferences
Store each member's notification preference alongside their push subscription: 'all' messages, 'urgent' only, or 'none'. Before sending a push notification, check the member's preference against the message's urgency flag. This respects member autonomy and reduces churn from notification fatigue.
How to set up push notifications in your PWA
- 1
Generate VAPID keys
Run npx web-push generate-vapid-keys and save the output. Set VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY in your backend environment, and VITE_VAPID_PUBLIC_KEY in your frontend environment.
- 2
Create a service worker (sw.js)
Add push event and notificationclick event listeners. Parse the notification payload and call self.registration.showNotification() with the title and body.
- 3
Register the service worker in your app
On app load, call navigator.serviceWorker.register('/sw.js'). Wait for registration to be ready before requesting push permission.
- 4
Request push permission and subscribe
Call Notification.requestPermission(). If granted, call pushManager.subscribe() with your VAPID public key (urlBase64ToUint8Array encoded). Send the resulting PushSubscription to your backend API to save.
- 5
Store the subscription in your database
Save the subscription endpoint, p256dh key, and auth key against the user's ID. Also store their notification preference (all / urgent / none).
- 6
Send push notifications on broadcast
When a message is sent, query subscriptions for the target audience filtered by preference. Use the web-push library to send a notification to each subscription endpoint. Remove any subscriptions that return 410 Gone.
Frequently Asked Questions
Ready to transform your organisation's communications?
Start sending targeted messages, push notifications, and event updates to your team — all from one simple platform.