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 || '/' }
}));
});What changes on the server
Nothing about delivery changes: Declarative Web Push messages still use RFC 8030 delivery, RFC 8291 encryption and VAPID. What changes is the payload — a JSON object with "web_push": 8030 and a notification member that the browser can display without running your service worker. Senders can therefore send one payload to every browser: Safari 18.4+ on iOS/iPadOS Home Screen apps and Safari 18.5 on macOS display it directly, while other browsers pass it to the worker, which reads the same fields.
What you trade for robustness
- Custom logic at display time only runs if you set
mutable: trueand have a worker that handles it. - Click handling is a
navigateURL — put campaign parameters in it if you measure clicks. - Fields outside the declarative format won’t display on Safari’s declarative path.
- You still need a manifest and Home Screen install on iPhone; Declarative Web Push doesn’t change Apple’s Home Screen rule.
Testing it
- Subscribe on an iPhone (iOS 18.4+) from a Home Screen web app.
- Send a declarative payload and confirm it displays even if your worker is broken (temporarily throw in the push handler on a test site).
- Send the same payload to Chrome and Firefox and confirm your fallback worker shows identical text.
- Check the click opens the
navigateURL.
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.
Do I still need a service worker for Declarative Web Push?
For Safari’s declarative path the worker isn’t required, but you’ll still want one for other browsers and for fallback handling.
Will Chrome support Declarative Web Push?
It has been proposed as a standard; check browser release notes rather than assuming support.
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 · Web push in Python with pywebpush · Django push notifications to the browser · Web push notifications in Ruby on Rails · Web push in Go with webpush-go · Angular push notifications with SwPush · Push notifications in Vue 3 and Nuxt · Push notifications in SvelteKit · All guides
Free for life. No limits.
Unlimited subscribers, campaigns and automations. No badges. About five minutes to install.