To send web push notifications from Node.js, install the web-push library, generate a VAPID key pair once, and save each browser’s push subscription in a database. Then call setVapidDetails with your keys and sendNotification with a subscription and a JSON payload. The library encrypts the message, and the browser’s push service delivers it to your service worker.
Node.js web push notifications don’t need Firebase or any paid service on the sending side. The protocol is an open standard, and the open-source web-push library handles the hard parts: VAPID signing and payload encryption. Below I cover the full flow, with code checked against web-push 4.0, the current version in November 2026.
What do you need to send Node.js web push notifications?
You need five pieces: HTTPS, a VAPID key pair, a service worker, a subscription store and a sender. Here’s what each one does.
| Piece | Purpose | Notes |
|---|---|---|
| HTTPS site | Service workers only run in secure contexts | localhost works for testing |
| VAPID key pair | Identifies your server to push services | Generate once; keep the private key secret |
| Service worker | Receives the push event and shows the notification | Serve it from your own domain |
| Subscription store | Saves each browser’s endpoint and keys | One row per browser, not per user |
| web-push package | Encrypts and sends each message | Version 4 needs Node.js 16 or newer |
The browser side is the same whatever language your server uses. So if you’ve read my PHP and Laravel guide, only the server code below is new.
How do you install web-push and create VAPID keys?
Install the package from npm, then generate the keys once with its command-line tool. Don’t generate new keys on every deploy, because existing subscriptions only work with the public key they were created with.
npm install web-push
npx web-push generate-vapid-keys --jsonSave the two values as environment variables, for example VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY. The public key goes to the browser. The private key stays on your server. My explainer on VAPID keys for web push covers what each key does and why losing the private key cuts you off from your subscribers.
How do you collect push subscriptions in the browser?
The browser creates a subscription when the visitor allows notifications. Your page registers a service worker, asks for permission on a click, calls pushManager.subscribe with your public key, and posts the result to your server.
// public/sw.js
self.addEventListener('push', (event) => {
const data = event.data ? event.data.json() : {};
event.waitUntil(
self.registration.showNotification(data.title || 'New update', {
body: data.body,
icon: data.icon,
data: { url: data.url || '/' }
})
);
});
self.addEventListener('notificationclick', (event) => {
event.notification.close();
event.waitUntil(clients.openWindow(event.notification.data.url));
});// on your page, inside a button click handler
const reg = await navigator.serviceWorker.register('/sw.js');
const sub = await reg.pushManager.subscribe({
userVisibleOnly: true,
applicationServerKey: VAPID_PUBLIC_KEY // the public key string
});
await fetch('/api/subscribe', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(sub)
});The web-push README shows the public key passed as a string, which current browsers accept. Some older tutorials convert it to a Uint8Array first; that works too. For more on scope and caching, see my guide to the service worker for web push.
How do you send a notification with web-push?
Set your VAPID details once, then call sendNotification for each subscription. Version 4 of web-push is an ES module without a default export, so import it as a namespace. On recent Node.js releases (20.19+ and 22.12+), require(‘web-push’) also works.
// server.mjs (Express)
import express from 'express';
import * as webpush from 'web-push';
webpush.setVapidDetails(
'mailto:[email protected]',
process.env.VAPID_PUBLIC_KEY,
process.env.VAPID_PRIVATE_KEY
);
const app = express();
app.use(express.json());
const subscriptions = new Map(); // use a real database in production
app.post('/api/subscribe', (req, res) => {
subscriptions.set(req.body.endpoint, req.body);
res.sendStatus(201);
});
app.post('/api/send', async (req, res) => {
const payload = JSON.stringify({
title: 'New post: Node.js web push',
body: 'Read the step-by-step guide',
url: '/blog/nodejs-web-push/'
});
for (const sub of subscriptions.values()) {
try {
await webpush.sendNotification(sub, payload, { TTL: 3600, urgency: 'normal' });
} catch (err) {
if (err instanceof webpush.WebPushError && (err.statusCode === 404 || err.statusCode === 410)) {
subscriptions.delete(sub.endpoint); // expired or unsubscribed
} else {
console.error(err.statusCode, err.body);
}
}
}
res.sendStatus(202);
});
app.listen(3000);The subject must be a mailto: address or an https: URL that push services can use to contact you. The web-push README notes that Safari’s push endpoint rejects a subject pointing at https://localhost, so use a real address even in testing.
Which sendNotification options matter?
Three options matter for most sends: TTL, urgency and topic. They map to headers defined in RFC 8030, the Web Push protocol.
| Option | What it does | Default in web-push |
|---|---|---|
| TTL | Seconds the push service keeps the message if the device is offline | Four weeks |
| urgency | very-low, low, normal or high; affects battery-saving delivery | normal |
| topic | Replaces an older undelivered message with the same topic | None |
| timeout | Socket timeout in milliseconds | None |
| headers | Extra request headers | None |
For news, a TTL of a few hours stops yesterday’s headline from arriving tomorrow. For a one-time code or alert, use a short TTL and high urgency. Also keep payloads small: RFC 8030 only requires push services to accept 4,096 bytes, so send a title, body and URL, not a full article.
How do you handle expired subscriptions and errors?
Delete a subscription when the push service answers 404 or 410. Those codes mean the subscription has expired or the visitor has unsubscribed, so retrying wastes requests. web-push throws a WebPushError with statusCode, headers and body, which makes the check simple.
Other errors need different handling:
- 400 or 403: usually a VAPID problem, such as a key mismatch or a bad subject. Check that the public key in the browser matches the private key on the server.
- 413: the payload is too large. Trim it.
- 429: you’re being rate limited. Back off and retry later.
At larger lists, don’t loop with await one by one. Send in batches with a concurrency limit, or put sends on a queue such as BullMQ, so one slow endpoint doesn’t hold up everyone else. MDN’s Push API reference covers the browser side of the same flow.
Does Node.js web push reach iPhone users?
Yes. Since iOS 16.4, Safari supports web push for sites added to the Home Screen, and web-push sends to Apple’s endpoint like any other. You need a web app manifest, and the visitor must add your site to the Home Screen before they can subscribe. See how to get web push working on iPhone for the full checklist.
Should you build it yourself or use a push panel?
Build it yourself if you only need a few alerts triggered by code and you have developers to maintain them. Use a panel if marketers or editors will send campaigns, because the DIY route gives you delivery but no editor, scheduling, segments or reports.
| Need | DIY with web-push | Push panel |
|---|---|---|
| Send an alert from code | Good fit | Works through an API |
| Campaign editor and scheduling | You build it | Included |
| Segments and click reports | You build it | Included |
| Expired subscription cleanup | You build it | Handled for you |
| Main cost | Developer time | Subscription or licence |
If you’re on Next.js, my guide to adding web push to Next.js shows the same library inside Server Actions.
Where does LaraPush fit?
LaraPush is a self-hosted web push panel you install on your own VPS. It handles subscriptions, campaigns, scheduling, segmentation and click reports, and its REST API has no call limits, so your Node.js app can trigger sends instead of encrypting messages itself. See the features overview, the setup guide and my notes on the push notification API for developers.
The trade-offs: you run the server, the licence covers one server, and there’s no free plan. Plans start from $499 one-time; check the pricing page for current prices. For a wider view, my roundup of push notification services compares SaaS and self-hosted tools.
Frequently asked questions
No. The web-push library sends straight to each browser’s push service using VAPID, so you don’t need a Firebase project or server key. Chrome subscriptions still travel through Google’s push service, but your code only needs the subscription endpoint and your VAPID keys.
Version 4 of web-push is an ES module without a default export. Import it with import * as webpush from ‘web-push’, or import the functions you need by name, such as sendNotification and setVapidDetails.
There’s no fixed limit in web-push itself; each send is one HTTPS request. Throughput depends on your server, network and concurrency. For large lists, send in batches or through a job queue, and remove subscriptions that return 404 or 410.
Yes. sendNotification accepts no payload, and the service worker still gets a push event. It must then show a notification anyway, because browsers require a visible notification for each push, so most sites send a small JSON payload instead.
It’s a contact point for push services, either a mailto: email address or an https: URL. Push services can use it to reach you if your sends cause problems. Avoid an https://localhost subject, which Safari’s push endpoint rejects.




