cometchat-react-push

Purpose

Web Push for CometChat chat. The web has no native VoIP-push equivalent for incoming-call ringing (see cometchat-react-calls/references/voip-and-web-push.md for that limit), but it does have Web Push for new-message notifications when the user's tab is backgrounded or closed. This skill wires the full path: client subscription → server webhook → push send → notification → click-through.

Not the same as the calls Web Push. Calls Web Push tries to ring the device through a closed tab (best-effort, browser-dependent). Chat Web Push notifies on new messages — fundamentally similar plumbing, different payload + UX. Many apps need both.

Read these other skills first:

• cometchat-core — provider pattern, login order
• cometchat-{react,nextjs,react-router,astro}-patterns — framework-specific Service Worker registration
• cometchat-react-calls/references/voip-and-web-push.md — calls-specific Web Push (overlap with this; both can coexist)
• cometchat-production — server-minted auth tokens (push payloads should NOT contain Auth Key)

Ground truth:

• Web Push spec — https://datatracker.ietf.org/doc/html/rfc8030
• VAPID — https://datatracker.ietf.org/doc/html/rfc8292
• Push API — https://developer.mozilla.org/en-US/docs/Web/API/Push_API
• CometChat dashboard PushNotifications (formerly Extensions → Enhanced Push Notifications)

---

1. Architecture

Browser (your React app)
  ├── Service Worker — long-lived; receives push events
  ├── Push subscription — issued by browser, sent to your server
  └── Notification UI — fired by SW on push event

CometChat backend
  └── Webhook → your push server when a message is sent

Your push server (Node, Cloudflare Worker, Lambda, etc.)
  ├── Stores push subscriptions per UID
  ├── Receives CometChat webhook
  └── Sends push payload via web-push lib → browser

Three pieces, all yours: client SW, push server, webhook integration. CometChat doesn't host the push server for you — its dashboard's "PushPlatform" config is for FCM/APNs (mobile), not Web Push.

---

2. Generate VAPID keys (server-side, one-time)

VAPID = Voluntary Application Server Identification — proves to the browser that the push originated from an authorized server.

npx web-push generate-vapid-keys

Output:

=======================================
Public Key: BLBz-...
Private Key: 9tT...
=======================================

Public key → client (env var). Private key → push server only (never ship to client).

---

3. Service Worker

public/sw.js (Vite / CRA / React Router) or app/sw.js (Next.js / Astro)

// Fired when a push payload arrives
self.addEventListener("push", (event) => {
  if (!event.data) return;

  let payload;
  try {
    payload = event.data.json();
  } catch {
    return;
  }

  if (payload.type !== "new_message") return;

  event.waitUntil(
    self.registration.showNotification(payload.senderName, {
      body: payload.preview,                          // truncated message
      icon: payload.senderAvatar ?? "/icons/chat.png",
      tag: `chat-${payload.conversationId}`,          // dedupe — replace prior unread for same conversation
      badge: "/icons/badge.png",
      data: {
        conversationId: payload.conversationId,
        senderUid: payload.senderUid,
        receiverType: payload.receiverType,           // "user" or "group"
      },
    }),
  );
});

// Fired when user clicks the notification
self.addEventListener("notificationclick", (event) => {
  event.notification.close();

  const data = event.notification.data;
  const targetUrl = data.receiverType === "group"
    ? `/messages?group=${data.conversationId}`
    : `/messages?user=${data.senderUid}`;

  event.waitUntil(
    clients.matchAll({ type: "window", includeUncontrolled: true }).then((wins) => {
      // Focus existing tab if open
      for (const w of wins) {
        if (w.url.includes(self.registration.scope)) {
          w.focus();
          w.postMessage({ type: "open_conversation", ...data });
          return;
        }
      }
      // Otherwise open a new tab
      return clients.openWindow(targetUrl);
    }),
  );
});

// Optional: fired when a notification is dismissed without click
self.addEventListener("notificationclose", (event) => {
  // Send a "dismissed" beacon to your server if you track this
});

---

4. Client-side registration

// cometchat/registerWebPush.ts
const VAPID_PUBLIC = import.meta.env.VITE_VAPID_PUBLIC_KEY;     // adjust prefix per framework

export async function registerWebPushForChat(uid: string): Promise<void> {
  if (!("serviceWorker" in navigator) || !("PushManager" in window)) return;

  // Register the SW (one-time per origin)
  const reg = await navigator.serviceWorker.register("/sw.js");

  // Wait for SW activation
  await navigator.serviceWorker.ready;

  // Ask permission — must be in response to a user gesture (click)
  const permission = await Notification.requestPermission();
  if (permission !== "granted") return;

  // Get or create subscription
  let subscription = await reg.pushManager.getSubscription();
  if (!subscription) {
    subscription = await reg.pushManager.subscribe({
      userVisibleOnly: true,                          // required by Chrome
      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC),
    });
  }

  // Send subscription to YOUR push server, keyed by uid
  await fetch("/api/push/subscribe", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ uid, subscription }),
  });
}

function urlBase64ToUint8Array(base64: string): Uint8Array {
  const padding = "=".repeat((4 - (base64.length % 4)) % 4);
  const raw = atob((base64 + padding).replace(/-/g, "+").replace(/_/g, "/"));
  return Uint8Array.from(raw, (c) => c.charCodeAt(0));
}

Call this from your CometChatProvider AFTER login resolves:

// CometChatProvider.tsx
useEffect(() => {
  if (!user) return;
  registerWebPushForChat(user.uid).catch((err) => {
    // surface to UI but don't block chat — push is opt-in
    console.warn("Web Push registration failed:", err);
  });
}, [user]);

The permission prompt rule: Chrome / Firefox / Safari all require permission requests in response to a user gesture. If you call Notification.requestPermission() from a top-level useEffect that runs on page load, browsers reject it. Best pattern: a "Enable notifications" button the user clicks once.

---

5. Listen for SW messages in the React app

// CometChatProvider.tsx
useEffect(() => {
  if (!("serviceWorker" in navigator)) return;

  const handler = (event: MessageEvent) => {
    if (event.data?.type === "open_conversation") {
      navigate(`/messages?${event.data.receiverType}=${event.data.conversationId}`);
    }
  };
  navigator.serviceWorker.addEventListener("message", handler);
  return () => navigator.serviceWorker.removeEventListener("message", handler);
}, [navigate]);

When the SW posts open_conversation, the React app navigates to the right thread.

---

6. Server-side push send

Your push server runs on Node.js / Cloudflare Worker / Lambda / Vercel Functions. The shape:

// server/push.ts
import express from "express";
import webpush from "web-push";
import { z } from "zod";

webpush.setVapidDetails(
  "mailto:notifications@yourapp.com",
  process.env.VAPID_PUBLIC!,
  process.env.VAPID_PRIVATE!,
);

const app = express();
app.use(express.json());

// 1. Client registers a subscription
app.post("/api/push/subscribe", async (req, res) => {
  const { uid, subscription } = req.body;          // validate with zod in production
  await db.savePushSubscription(uid, subscription);
  res.status(204).send();
});

// 2. CometChat fires a webhook when a message is sent
app.post("/webhook/cometchat/message-sent", async (req, res) => {
  const { receiver, sender, data } = req.body.data;

  // Don't notify the sender — they sent the message
  const subs = await db.getPushSubscriptions(receiver);
  if (!subs.length) return res.status(204).send();

  const payload = JSON.stringify({
    type: "new_message",
    conversationId: receiver,
    senderUid: sender.uid,
    senderName: sender.name,
    senderAvatar: sender.avatar,
    preview: truncate(data.text, 80),
    receiverType: data.entityType,                 // "user" or "group"
  });

  // Send to all of receiver's subscriptions in parallel; clean up dead ones
  await Promise.allSettled(
    subs.map(async (sub) => {
      try {
        await webpush.sendNotification(sub, payload);
      } catch (err: unknown) {
        if ((err as { statusCode?: number }).statusCode === 410) {
          await db.removePushSubscription(receiver, sub);   // browser unsubscribed
        }
      }
    }),
  );

  res.status(204).send();
});

function truncate(s: string, n: number) {
  return s.length <= n ? s : s.slice(0, n - 1) + "…";
}

app.listen(3000);

The skill writes a starter version of this server file (server/push.example.ts) with a README pointing at env vars; the user owns the actual deployment.

---

7. CometChat webhook setup (manual)

In the CometChat dashboard:

1. Navigate to Webhooks.
2. Click + Webhook.
3. URL: https://your-push-server.example.com/webhook/cometchat/message-sent
4. Trigger: Message sent
5. Verification: copy the signing secret to your push server's env (COMETCHAT_WEBHOOK_SECRET).

The webhook fires for EVERY message — your server filters out the sender, dedupes per conversation, and respects user notification preferences.

---

8. Webhook signature verification

import crypto from "crypto";

app.use("/webhook/cometchat", (req, res, next) => {
  const signature = req.header("x-cometchat-signature");
  const expected = crypto
    .createHmac("sha256", process.env.COMETCHAT_WEBHOOK_SECRET!)
    .update(JSON.stringify(req.body))
    .digest("hex");
  if (signature !== expected) return res.status(401).send({ error: "invalid signature" });
  next();
});

Without this, anyone with your endpoint URL can flood your users with fake notifications.

---

9. Browser support matrix + iOS PWA caveat

Browser	Web Push	Notification while closed	Notes
Chrome desktop	✓	✓ if Chrome process alive	Service Worker terminates after ~30s idle
Edge desktop	✓	✓	Same as Chrome
Firefox desktop	✓	✓	Slightly more SW survival
Safari 16+ desktop	✓	✓ if Safari running	macOS 13+
Safari 16.4+ iOS	✓	Only when added to Home Screen as PWA	Critical caveat
Chrome mobile	✓	✓	Aggressive throttling on Android
Edge mobile	✓	✓	Same as Chrome mobile

iOS PWA-only requirement: iOS 16.4+ supports Web Push, but ONLY for sites added to the Home Screen as a PWA. Safari-the-browser-app does NOT receive Web Push. To unlock iOS Web Push:

1. App must have a manifest.json (PWA manifest)
2. User must use Safari → Share → "Add to Home Screen"
3. Subsequent push subscriptions and notifications work as expected

This is a real production constraint. The skill detects whether the project ships a manifest.json and warns if not.

---

10. Framework-specific Service Worker registration

Vite / React (CRA)

public/sw.js is served from /sw.js. register("/sw.js") works directly.

Next.js (App Router)

Service Workers + Next.js have a known gotcha: the SW can't be inside app/ because Next handles those routes. Place it in public/sw.js and serve from /sw.js. Register from a "use client" component that runs after hydration.

Next.js (Pages Router)

Same — public/sw.js.

React Router

public/sw.js works. If using SSR (loaders), the SW registration code must be guarded by typeof window !== "undefined".

Astro

Place the SW at public/sw.js. Register from a client:only="react" island.

The framework-specific patterns skills cover the SSR guards in detail.

---

11. HTTPS requirement

Service Workers + Push API both require HTTPS (or localhost for dev). The skill detects the dev server protocol and warns:

⚠️  Web Push requires HTTPS or localhost. Your dev server is running on http://192.168.x.x.
   Web Push subscriptions will fail. Either:
   - Use http://localhost (Chrome/Firefox/Safari all allow Push API on localhost), or
   - Set up HTTPS dev (mkcert, ngrok, or Vite's --https flag)

For production, the Vercel / Netlify / Cloudflare default deploys are HTTPS — no extra work.

---

12. Anti-patterns

1. Calling Notification.requestPermission() on page load. Browsers reject this. Wire to a user-clicked "Enable notifications" button.
2. Sending the Auth Key in push payloads. Push payloads are visible in the SW; never include credentials. Use the user's UID as a key into your server's session store.
3. Missing webhook signature verification. Without HMAC verification, anyone with the URL can spoof notifications.
4. Showing notifications even when the chat tab is open. Check clients.matchAll() from the SW and skip if the user already has the chat focused.
5. Skipping the iOS PWA warning. iOS users will silently get nothing. The skill explicitly tells them to "Add to Home Screen."
6. Service Worker registered before login completes. Race conditions where the subscription exists but the server doesn't know whose UID it belongs to. Register from inside the auth state effect.
7. Forgetting subscription cleanup on logout. The previous user's subscription keeps notifying them with the new user's messages. Call subscription.unsubscribe() and DELETE the server record on logout.

---

13. Logout cleanup

async function unsubscribeWebPush(uid: string): Promise<void> {
  const reg = await navigator.serviceWorker.getRegistration();
  if (!reg) return;
  const subscription = await reg.pushManager.getSubscription();
  if (!subscription) return;

  await fetch("/api/push/unsubscribe", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ uid, subscription }),
  });
  await subscription.unsubscribe();
}

Call this from your logout flow before CometChat.logout().

---

14. Verification checklist

• public/sw.js (or framework equivalent) exists and listens for push + notificationclick events
• VAPID public key in client env vars (correct framework prefix)
• VAPID private key in server env, NOT client
• Notification.requestPermission() triggered from a user gesture, not page load
• Push subscription registered AFTER login resolves
• Subscription POSTed to your push server, keyed by CometChat UID
• CometChat dashboard webhook configured for Message sent events
• Webhook signature verification on the push server (HMAC SHA256)
• Notifications dedupe per conversation via tag field
• notificationclick focuses existing tab via clients.matchAll OR opens new tab
• Foreground tab does NOT show notifications (check tab focus before showNotification)
• Logout flow calls subscription.unsubscribe() and deletes server record
• HTTPS or localhost only (warned otherwise)
• manifest.json shipped if iOS users are expected (PWA caveat)
• Server cleanup of dead subscriptions on 410 response

---

15. Pointers

• cometchat-react-calls/references/voip-and-web-push.md — Web Push for incoming calls (overlap; both can coexist on the same SW)
• cometchat-{react,nextjs,react-router,astro}-patterns — framework-specific SSR handling
• cometchat-production — auth tokens, security
• cometchat-troubleshooting — Web Push debugging (chrome://serviceworker-internals, Firefox about:debugging)