PWAs on Safari for macOS (Dock apps)
Published
In one line: since macOS Sonoma with Safari 17, a website can be added to the Dock as a web app via Add to Dock. It then launches in its own standalone window — no Safari toolbar — with its own icon, and (for installed Dock apps) supports notifications and Web Push. A web app manifest lets you control how that Dock app looks and behaves.
How installation works
Section titled “How installation works”- Add to Dock. With a site open in Safari, choose File → Add to Dock (also reachable from the Share menu). Safari creates a standalone web app and places it in the Dock; it also appears in Launchpad / Applications.
- Works for any site. You don’t need a manifest to add a site to the Dock — Safari will derive a name and icon. A manifest lets you control the result (see below).
- User-initiated. Per WebKit, the user is in charge of choosing what becomes a web app — they start Add to Dock themselves.
How the manifest shapes the Dock app
Section titled “How the manifest shapes the Dock app”When a web app manifest is present, Safari uses it to customize the installed app. Per WebKit’s Safari 17 notes, a manifest can set the app’s display mode, name, theme color, and start URL — so a complete manifest produces a branded, purpose-built Dock app rather than a Safari-derived shortcut.
What works once installed
Section titled “What works once installed”- Standalone window. The app opens in its own window without the Safari toolbar, using your manifest identity.
- Service workers. Service workers run for caching and offline support, subject to WebKit’s lifecycle and storage rules.
- Notifications & Web Push. Installed Mac web apps support the Notifications API and Web Push, so they can re-engage users like a native Mac app.
- System integration. The app behaves like a Mac app: its own Dock icon, app switcher entry, and window management.
How macOS differs from iOS
Section titled “How macOS differs from iOS”Although both are WebKit, the macOS web-app experience is distinct from iOS “Add to Home Screen”:
- Entry point. macOS uses Add to Dock (File/Share menu) on the desktop; iOS uses Add to Home Screen on the device.
- Form factor. macOS web apps are resizable desktop windows with full window management; iOS apps are full-screen mobile surfaces.
- Shared platform basis. Both run on WebKit, so plan around its storage model and feature set rather than assuming Chromium-only capabilities.
Storage and eviction
Section titled “Storage and eviction”Mac web apps use WebKit’s per-origin storage. WebKit may evict data by origin when the total storage usage across all origins exceeds the overall quota; storage marked persistent is exempt from that eviction. Treat cached data as potentially removable: re-validate and re-sync important data on launch, and keep the source of truth on your server.
Practical guidance
Section titled “Practical guidance”- Ship a full manifest. Provide
name, icons,display, theme color, andstart_urlso the Dock app is branded and purpose-built. - Tell users how to install. Users add the app via File → Add to Dock, so a short hint pointing macOS visitors to that menu helps them discover it.
- Don’t assume persistence. Request persistent storage where it matters, and re-sync important data on launch.
- Test on real macOS. Verify standalone window behaviour, push, and icons in an actual Sonoma-or-later Safari install.