@mmmike/web-push

The whole Web Push flow, from subscribing in the browser to sending from the server, in one zero-dependency package.

Adding push notifications to a site is usually two jobs. A library handles sending, and the browser half is left to you: asking for permission, replacing a subscription made with an old VAPID key, uploading it to your server, and a service worker pieced together from blog posts. The usual library is also built on Node's crypto and https, so outside Node it runs on each runtime's emulation of Node.

This package does both halves, and its quickstart has a service worker to copy. It's built on fetch and the Web Crypto API, which Node, Bun, Deno and Cloudflare Workers each implement natively, so the server side runs the same on all of them with no Node emulation underneath.

To see it work first, send yourself a notification from the docs site. A Cloudflare Worker encrypts and sends it with this package.

npm install @mmmike/web-push

From zero to a notification

1. Make a VAPID key pair, once. The public key goes to the browser and the private key stays a server secret.

import { generateVapidKeys } from "@mmmike/web-push/vapid";

const { publicKey, privateKey } = await generateVapidKeys();

2. Subscribe in the browser. Save the quickstart's service worker as /sw.js, then:

import { subscribe, sendSubscriptionToServer } from "@mmmike/web-push/client";

await navigator.serviceWorker.register("/sw.js");

button.addEventListener("click", async () => {
	const result = await subscribe(publicKey);
	if (result.status === "subscribed") {
		await sendSubscriptionToServer(result.subscription, "/api/push/subscribe");
	}
});

Safari and Firefox only show the permission prompt in response to a click, so call subscribe from one.

3. Send from the server. The payload is the title, body and url that service worker reads.

import { sendPushNotification } from "@mmmike/web-push/send";

const delivered = await sendPushNotification(
	subscription,
	{ title: "New message", body: "Ada replied to your post", url: "/inbox" },
	{ publicKey, privateKey, subject: "mailto:you@example.com" },
);
// false only for 404/410, a subscription that's gone; every other failure throws
if (!delivered) await store.delete(subscription.endpoint);

To send one notification to a list of subscribers, sendPushBatch caps how many sends run at once and sorts the results into delivered, gone and failed. See sending to many.

Specs and size

• RFC 8291 and RFC 8292. aes128gcm encryption and VAPID. There's no dependency tree to audit. Encryption is in src/encrypt.ts and VAPID signing in src/vapid.ts, both on Web Crypto, and a test pins the encryption's output byte-for-byte to RFC 8291's Appendix A test vector.
• Browsers. Chrome, Edge, Firefox, Opera and Samsung Internet, Safari 16+ on macOS 13+, and Safari on iOS 16.4+ for web apps added to the home screen.
• Small. Minified and gzipped per subpath entry, 1.3 kB for the browser client and 3.6 kB for the server. The size badge measures the whole package, ~4.6 kB.

Coming from web-push?

web-push is the established choice, and on Node it works well. Elsewhere it runs on each runtime's emulation of Node, and on Deno, Supabase and Cloudflare Workers that emulation has broken it before being fixed. It also brings 16 packages: a minimal Worker that sends with it uploads about 51 kB gzipped and takes longer to start, where one using this package uploads about 5 kB and starts as fast as an empty Worker. Both sizes are unminified, as wrangler builds by default, and CI measures them on every push. And it stops at the server.

The full comparison has the measurements and the bug history, and sets this package against the edge-native alternatives too. The migration guide keeps your stored subscriptions, keys and service worker.

Docs

• The quickstart goes from VAPID keys to a first notification.
• Build a complete app walks through one app that runs on Node, Bun, Deno or Cloudflare Workers.
• The recipes cover sending to many, handling errors, collapsing and expiring notifications, rotating keys, runtime setup, authenticated uploads, extension service workers and securing endpoints.
• The API reference is generated from the JSDoc.
• For LLMs, there's llms.txt and a Markdown copy of every page.
• Coding agents get AGENTS.md in the installed package, with the rules for using it and a map of its entry points.

License

MIT