# PWAs on Safari for macOS (Dock apps)

> How web apps install and run on macOS via Safari's Add to Dock — what macOS Sonoma and Safari 17 introduced, how the manifest shapes the Dock app, what works (push, notifications), and how it differs from iOS.

**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

- **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

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

- **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

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

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

- **Ship a full manifest.** Provide `name`, icons, `display`, theme color, and `start_url` so
  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.