PWAs on a Mac: what it does and where it breaks down

The phrase covers more ground than it looks like it does. Someone reading about PWAs on a Mac is usually reading three different mechanisms described in the same sentence, because the end result looks identical from the Dock. An icon appears. Clicking it opens a window with no address bar. That surface similarity hides differences that only show up later, when a login goes missing, a notification never arrives, or a link opens somewhere unexpected. Knowing which mechanism produced the icon is what makes those later problems solvable instead of mysterious.

Three mechanisms, one result

The first mechanism is Safari's Add to Dock, available since macOS Sonoma 14. It works on any webpage. No manifest is required, and no installability test runs. Safari builds a window, names it, and drops it into the Applications folder inside the home folder.

The second is a Chromium browser's install command, reached through More, then Cast, save, and share, then Install page as app. Chrome and Edge both run an installability check first, and when a site passes, an install icon appears in the address bar on its own. When a site fails the check, the menu item still works. The site becomes what the Chrome team describes as a manual app rather than a PWA install.

The third is a separate program that builds the app bundle for you, sometimes on top of a Chromium browser already installed on the machine, sometimes with its own embedded runtime. These tools exist because the first two mechanisms stop at what the browser vendor decided to expose.

The distinction matters because the three do not share storage, do not share settings, and cannot see each other. A site installed through Safari and the same site installed through Chrome produce two apps that behave as two unrelated programs. MDN states the rule plainly.

PWAs installed by a browser remain specific to this browser. This means that the browser that was used to install a PWA is the one used to run that PWA. It also means that you can install the same PWA from a different browser and that the two apps will behave as two different instances and will not share any data. Source: developer.mozilla.org

One browser is missing from the list entirely. Firefox on macOS has no install command, and MDN records that Firefox requires a PWA extension for this. Anyone whose daily browser is Firefox is choosing a second browser for this task whether they intended to or not.

What macOS actually receives

An installed web app is a real bundle in the filesystem, not a bookmark. That is the substantive difference from saving a link, and it is what unlocks the operating system integrations.

The bundle lands in the Applications folder of the home folder, which is a different location from the system wide Applications folder at the root of the disk. Both appear in Spotlight. Only one shows up when someone opens the root level folder in the Finder looking for the thing they just made. Apple's documentation names the location directly, and it is also where the app has to be dragged from when the time comes to delete it.

Once the bundle exists, macOS treats it like any other program. It appears in the application switcher. It can be pinned to the Dock. It can be added as a login item so that it opens automatically at sign in. It can be searched for by name rather than by URL. On the Chromium side there is an equivalent switch: right clicking the app at chrome://apps offers Launch at startup.

Notification handling is the integration that surprises people most, because it depends on where the permission prompt gets answered. Apple's support page is specific about it.

Web apps support an additional notifications feature: The number of unread notifications appears as a red badge on the app's icon in the Dock. To use this feature, respond to the website's notifications request in the web app, not in Safari. Source: support.apple.com

The same page notes that the app then appears in Notifications settings under its own name rather than under the site's URL, which is the only way to confirm the permission actually landed on the app.

What the manifest controls, and what it does not

A web app manifest is a JSON file the site publishes describing how it wants to be presented once installed. How much of it survives depends on which mechanism did the installing.

Chromium browsers use the manifest as the gate. The documented requirements are an icons entry that includes a 192 by 192 pixel icon and a 512 by 512 pixel icon, a start_url, a display value of fullscreen, standalone, or minimal-ui, and prefer_related_applications set to anything other than true. The page must also be served over HTTPS. Failing any of these does not block installation now, but it does mean the automatic install badge never appears in the address bar and the site is installed as a manual app instead.

Safari reads a narrower set. The WebKit announcement for Safari 17 lists display mode, name, theme color, and start URL as the fields a manifest can use to customise the presentation. The same announcement makes the fallback explicit: a site with no manifest at all still opens in its own window when its Dock icon is clicked. Safari's Add to Dock is not an installability check, it is a window builder that reads a manifest if one happens to exist.

Two consequences follow. A site that fails every Chromium criterion can still become a perfectly usable Safari web app, because Safari never tested it. And a site that publishes a careful manifest with app shortcuts, file handlers, and share targets will see most of that ignored on the Safari route, because those fields are not on the list.

Where the engine boundary shows

An installed web app is still the browser engine with the chrome hidden. Nothing about installation changes how the page runs, and the places where that becomes visible are consistent enough to predict.

Storage separation is the first. Safari copies the site's cookies into the web app when it is created, and nothing else. Anything the site kept in local storage, IndexedDB, or a service worker cache stays behind in the browser. A site that reconstructs state from local storage rather than cookies will look signed out on first launch even though the cookies came across.

Scope is the second. When a link points somewhere outside the app's start URL, the window has to decide whether to follow it or hand it to a browser. Sign in flows are where this bites, because an OAuth redirect leaves the site's own domain by design and comes back. Some flows survive the round trip cleanly. Some open a popup that never returns focus to the parent window.

Display mode is the third. Only standalone and minimal-ui are supported on desktop operating systems, so a manifest asking for fullscreen gets something else. A site that assumed a browser toolbar would always be present for navigation loses back and forward on the Chromium route, because a standalone window has no visible controls. Safari keeps a thin toolbar with back, forward, and share, and its settings panel has a Show navigation controls switch that turns even that off.

The sites where it stops working well

Not every daily tab is a good candidate, and the pattern is fairly consistent. What matters is whether the site was built expecting a browser around it.

Anything that opens a new window as part of a normal workflow is the first group. Document editors that pop out a preview, admin panels that open a report in a second tab, tools with a built in help viewer. In a tabbed browser these land next to the current tab. In a standalone window they either spawn a bare child window with no controls or get handed to the default browser, where the session may not exist.

Anything depending on browser extensions is the second group. Safari web apps carry Safari extensions, and the settings panel has an Extensions tab to enable them per app. A Chromium installed app inherits the extensions of the profile that created it. A password manager set up in one profile is simply absent from an app built in another.

Downloads and printing form the third group. Both work, but the destination and the print dialog belong to the engine behind the window, which is not necessarily the browser that gets used for everything else. A file saved from a Safari web app follows Safari's download location even when Chrome is the default browser, and the notification that a download finished appears against the web app rather than against Safari.

There is a fourth group that gets overlooked because the site itself is fine. Any workflow that starts somewhere else and ends at this site breaks the moment the entry point is a link in mail or chat. Clicking that link opens the default browser, not the installed app, because macOS routes URLs by protocol handler and a web app does not claim one. The app and the browser then hold separate sessions for the same service, and which one a task lands in depends on how the task started. Sites used only by opening them directly are unaffected. Sites that are the destination of links sent by other people will keep splitting across two windows until the habit changes.

Behaviour	Safari web app	Chromium installed app	Separate wrapper tool
Requires a manifest	No	No, but the install badge needs one	No
Storage shared with the browser	No, cookies copied once	Yes, tied to the source profile	Depends on the tool
Extensions available	Safari extensions, per app	Extensions of the source profile	Depends on the tool
Toolbar in the window	Thin, can be hidden	None in standalone mode	Depends on the tool
Where the bundle lives	Applications folder in the home folder	Managed at chrome://apps	Usually the Applications folder
Deleting it	Drag to the Trash	Uninstall from the app window	Tool specific

How to tell which mechanism built an existing icon

For an icon that already exists and is misbehaving, identifying its origin takes under a minute and determines every fix that follows.

Open the app and look at the menu bar. A Safari web app shows its own name as the application menu, and choosing Settings from that menu opens a panel with Application Name, Application URL, Icon, Show navigation controls, and Show color in title bar, plus Privacy and Extensions tabs. That panel is unique to this route. A Chromium app has no such panel. Its controls live in the three dot menu inside the window and in the browser at chrome://apps, and the uninstall command sits in the app's own menu with a checkbox for whether to delete the site data along with it.

The filesystem gives the same answer. A Safari web app sits in the Applications folder inside the home folder. Wrapper tools generally place their output in the main Applications folder and often ship a manager window listing everything they built.

Knowing the origin locates the login, which is the question behind most of the confusion. Safari route: its own cookie jar, seeded once at creation. Chromium route: the profile that built it, which means signing out in that profile signs out the app. Wrapper route: read the tool's documentation, because this is exactly the thing wrapper tools differ on.

What to change first

Pick one site that is open all day and build it through the browser already in daily use, then leave it alone for a week and note what breaks. The Guide walks through the creation steps and the settings worth changing at the start, and Supported services shows which sites are commonly pulled out of the tab strip. If the week turns up limits the browser route cannot clear, Kagemusha covers what a dedicated tool takes over.