Migrate from a native app to a PWA
Published
A Progressive Web App is a web application that the OS installs and launches like a platform-specific app. It ships through a URL, updates on the next load, and runs in the engine of the browser that installed it. To migrate a native app, map its features to web equivalents and their compatibility entries. Add a manifest and service worker to make the existing web property installable. Plan installation and removal for each OS. These flows differ from those of a store app.
You need the native app’s feature list, a web version of the product (or the decision to build one), and a domain served over HTTPS.
Inventory native features against web capabilities
Section titled “Inventory native features against web capabilities”List every OS integration the native app relies on and check browser support before
promising it. Include push notifications (Web Push), app icon
badges (Badging), sharing into the app
(Share target), opening files
(file_handlers), payments
(Payment Request), and hardware such as
Bluetooth, USB, and NFC (Capabilities). Each entry’s compatibility
table gives the per-browser, per-OS position with a verification date; the iOS Safari
row also covers Chrome, Edge, and Firefox on iOS, which embed WebKit there. For each feature, record the web equivalent in one column. Use two more columns for the platforms
where it is missing and the fallback you will ship there. Features with no acceptable fallback are the reason to keep a native build for that
platform, and the inventory records the reasons for that decision.
Make the web property installable
Section titled “Make the web property installable”Two files turn the site into an installable app. The manifest supplies the identity and
launch metadata; MDN’s installability guide lists the members Chromium browsers require as
name or short_name, icons with 192 px and 512 px entries, start_url, and display:
{ "id": "/", "name": "Field Notes", "short_name": "Notes", "start_url": "/?source=pwa", "scope": "/", "display": "standalone", "theme_color": "#1f4e79", "background_color": "#ffffff", "icons": [ { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" }, { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" } ]}The service worker is registered from the page and keeps the shell available offline, the behaviour native users take for granted. The registration is feature-detected so the page still loads in a browser without the API:
if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js').catch((error) => { console.error('Service worker registration failed:', error); });}/sw.js itself precaches the shell on install and answers from cache on fetch;
Getting started contains a complete worker to copy. Manifest and
service worker are independent: Firefox desktop runs service workers but does not install from
a manifest (MDN: “Firefox does not support installing PWAs using a manifest file”), so verify
each on its own compatibility entry.
Plan the install moment per OS
Section titled “Plan the install moment per OS”Store users are used to one install path; PWA install differs by OS and the migration page
must say so. MDN’s installing guide describes the available flows. On desktop Chrome and Edge an install
icon appears in the URL bar when the page qualifies; mobile browsers put the command in the
browser menu; Safari on iOS installs through the “Add to Home Screen” UI, available from the
Share menu in Chrome, Edge, Firefox, and Orion too from iOS 16.4; on macOS 14 (Sonoma) Safari
adds File > Add to Dock…. MDN also notes that an installed PWA is tied to the browser
that installed it: a user who installs from Edge and later from Chrome has two copies. If the
native app stays on the stores during the transition, declare it in related_applications
and use navigator.getInstalledRelatedApps() (top-level secure context only) to hide the web
install promotion for users who still have it.
Tell users how to launch and remove it
Section titled “Tell users how to launch and remove it”Launch behaviour matches a native app. MDN states that “clicking on the application icon
opens the PWA, even when the user is offline”, in a standalone window without browser UI when
the manifest asks for it. Removal is where support tickets come from, so document it per OS
from MDN’s guide. On desktop, the installed window’s menu offers an uninstall link, and Chrome
lists installed apps at chrome://apps while Edge lists them at edge://apps; on most mobile
OSes a PWA uninstalls like any app from the apps settings.
See also
Section titled “See also”- Getting started
- Make it installable
- Distribute a PWA via app stores
- PWAs on iOS and Safari
- Installing and uninstalling web apps (developer.mozilla.org)
- Making PWAs installable (developer.mozilla.org)