This is a lightweight server for sending web push notifications to web applications. It provides simple APIs to register push notification subscriptions and send notifications to all subscribers or to specific subscribers based on their endpoint.
The server generates VAPID keys for secure Web Push Authentication and handles the subscription and notification delivery processes. This makes it easy to add push notifications to your web applications without handling all the complex details of the Web Push protocol.
- Node.js: JavaScript runtime environment
- Express: Web server framework
- web-push: Library for sending web push notifications
- body-parser: Middleware for parsing JSON request bodies
- cors: Middleware for enabling Cross-Origin Resource Sharing
- Node.js (v14 or higher)
- npm (Node Package Manager)
- Clone the repository:
git clone <repository-url>
cd web-push- Install dependencies:
npm install- Start the server:
npm run dev # For development with auto-restart
# or
npm start # For productionThe server will start on port 3000 (or the port specified in the PORT environment variable) and generate VAPID keys on startup. You should save these keys for future use rather than generating new ones each time.
Integration with Your Web Application Register a Service Worker in your web application that can receive push notifications.
- Get the VAPID public key from this server via the
/api/vapid-public-keyendpoint. - Subscribe to push notifications using the public key and the browser's Push API.
- Send the subscription details to this server via the /api/subscribe endpoint.
- Send push notifications by making POST requests to the /api/send-notification endpoint.
Get VAPID Public Key
GET /api/vapid-public-key
Returns the VAPID public key needed to subscribe to push notifications.
Response:
{
"publicKey": "BFKVAsJfeLSvCGvNpP_xCZkTK3rXxCGXvfO1Ft2i4-a0Dip-S_bvjlhP92s00gy0BqYVSHSgoeF_VjQz_SVOr9o"
}Subscribe to Push Notifications
POST /api/subscribe
Registers a new push notification subscription.
Request Body:
{
"endpoint": "https://fcm.googleapis.com/fcm/send/example-endpoint",
"expirationTime": null,
"keys": {
"p256dh": "base64-encoded-key",
"auth": "base64-encoded-auth-secret"
}
}Response:
{
"success": true,
"message": "Subscription added successfully"
}Send Notification to All Subscribers
POST /api/send-notification
Sends a push notification to all registered subscribers.
Request Body:
{
"title": "Notification Title",
"body": "Notification message content",
"icon": "https://example.com/icon.png",
"tag": "notification-tag",
"data": {
"url": "https://example.com/details"
},
"actions": [
{
"action": "view",
"title": "View Details"
},
{
"action": "dismiss",
"title": "Dismiss"
}
]
}Response:
{
"success": true,
"message": "Notifications sent successfully to 3 subscribers"
}Send Notification to a Specific Subscriber
POST /api/send-notification/:endpoint
Sends a push notification to a specific subscriber identified by their endpoint.
URL Parameters:
- endpoint: URL-encoded endpoint of the subscription
Request Body: Same as for
/api/send-notification
Response:
{
"success": true,
"message": "Notification sent successfully"
}Returns a list of all registered subscriptions (for debugging purposes).
Response:
{
"count": 2,
"subscriptions": [
{
"endpoint": "https://fcm.googleapis.com/fcm/send/example-endpoint-1",
"keys": {
"p256dh": "ABCDEFGHIJ...",
"auth": "ABCDE..."
}
},
{
"endpoint": "https://fcm.googleapis.com/fcm/send/example-endpoint-2",
"keys": {
"p256dh": "KLMNOPQRST...",
"auth": "FGHIJ..."
}
}
]
}- If you're experiencing issues with sending notifications:
- Check subscription validity: Ensure the subscription object is valid and complete with endpoint and keys.
- VAPID key issues: Try using consistent VAPID keys instead of generating new ones on each server start.
- Browser support: Make sure the browser supports Web Push API.
- Service worker registration: Verify that your service worker is correctly registered and handling push events.
- Permissions: Ensure the user has granted notification permissions in their browser.
ISC