PusharooDeclarative Web Push, explained
Apple’s WebKit team introduced a way to show web push notifications without running a service worker. The browser reads a standard JSON message and displays it itself.
- Declarative Web Push lets the browser display a notification from JSON without a service worker running.
- Supported for Home Screen web apps on iOS/iPadOS 18.4+ and in Safari 18.5 on macOS.
- A payload with "web_push": 8030 and a notification object (title + navigate) is handled declaratively.
- It’s backwards compatible: other browsers can pass the same object to showNotification() in a worker.
Why Apple built it
Classic Web Push wakes a service worker for every message, and the worker must show a notification or risk losing the subscription. That costs battery and fails if the worker has a bug. WebKit’s answer, announced in its “Meet Declarative Web Push” post and shipped in Safari 18.4 for iOS/iPadOS Home Screen web apps (read Nov 12, 2026), is a push message the browser can display directly. An optional service worker can still modify the notification; if it fails, the declarative message is the fallback.
The payload format
{
"web_push": 8030,
"notification": {
"title": "Back in stock: Linen Shirt",
"body": "Size M is here again — 14 restocked.",
"navigate": "https://yourstore.com/p/linen-shirt",
"lang": "en-US",
"dir": "ltr",
"silent": false,
"app_badge": "1"
}
}"web_push": 8030 (a nod to RFC 8030) opts the message into declarative handling. title and navigate are required; navigate is the URL opened on tap. app_badge updates the icon badge where the Badging API is supported.
Subscribing without a worker
// Supported where window.pushManager exists (Safari 18.4+ in Home Screen web apps)
const sub = await window.pushManager.subscribe({
userVisibleOnly: true,
applicationServerKey: vapidPublicKeyBytes
});If a root-scoped service worker is also registered, it shares the same subscription. Sending is unchanged: the same encrypted, VAPID-signed request as any web push (protocol).
Compatibility strategy
| Browser | What happens with a declarative payload |
|---|---|
| Safari 18.4+ iOS Home Screen / 18.5+ macOS | Displayed by the browser; worker optional |
| Chrome, Edge, Firefox, older Safari | Delivered to your service worker as a normal push; read notification and call showNotification() |
// sw.js — handle both shapes
self.addEventListener('push', e => {
const d = e.data ? e.data.json() : {};
const n = d.web_push === 8030 ? d.notification : d;
e.waitUntil(self.registration.showNotification(n.title, {
body: n.body, icon: '/icon-192.png', data: { url: n.navigate || n.url || '/' }
}));
});Should you adopt it now?
- If you build your own stack and have many iPhone Home Screen users: yes, sending the declarative shape is low-risk and more robust there.
- Keep your service worker — Chrome, Firefox and Edge still need it.
- Watch browser release notes; other engines may adopt the format over time.
Background on Apple’s Home Screen requirement: web push on iPhone and Safari on the Mac.
Questions
Does Declarative Web Push work in Chrome?
Chrome doesn’t display declarative payloads by itself today, but your service worker can read the same JSON and show it, so one payload works everywhere.
Do I still need a service worker?
For Apple platforms that support Declarative Web Push, no. For other browsers, yes. Most sites keep one.
Does Declarative Web Push work in a regular Safari tab on iPhone?
No. On iPhone and iPad, web push — declarative or classic — requires a Home Screen web app.
Keep reading
Safari push notifications on the Mac
Standard Web Push in Safari on macOS 13+, settings, Dock web apps and Apple’s Declarative Web Push.
Web push on iPhone and iPad, explained honestly
The Home Screen rule, the manifest you need, and how to guide iPhone visitors without friction.
Service worker push events, done right
push and notificationclick handlers, focusing open tabs, action buttons, subscription changes and pitfalls.
The Web Push protocol, explained
RFC 8030 delivery headers, RFC 8291 encryption, RFC 8292 VAPID, status codes and payload size.
More in Developers: The Web Push API in JavaScript: a working example · VAPID keys for web push, explained · Web push notifications with Node.js · Web push notifications in PHP · Laravel browser push notifications (no Firebase) · Web push notifications in React and Next.js · Firebase web push vs. standard web push · All guides
Free for life. No limits.
Unlimited subscribers, campaigns and automations. No badges. About five minutes to install.