v147 · PWA · Web APIs

PWA origin migration

A new manifest field lets developers migrate an installed Progressive Web App from one same-site origin to another — preserving user trust, permissions, and the installed app identity — without forcing users to uninstall and reinstall.

concepts

  1. Manifest Config Explorer

    Side-by-side view of the destination manifest, old-origin association file, and optional old manifest, highlighting migrate_from, allow_migration, migrate_to, and install_url.

  2. Migration Timeline

    Step-by-step animated walkthrough of what happens when a user with the app installed visits the old origin after migration is declared: browser detection, service worker handoff, and identity transfer.

  3. PWA Origin Migration Checklist

    Enter current and target origins to get a live validation checklist for same-site, HTTPS, bare-origin, authorization, behavior, and redirect-safe install_url requirements, with generated manifest and association JSON.

  4. Push Subscription Migrator

    The hardest part of PWA migration: push notification subscriptions. Reads the current PushManager subscription, walks through the 3-step migration handshake (old SW sends migration push → user visits new origin → new SW subscribes), and shows a browser compat table for the applicationServerKey transfer approach.

  5. Compatibility Lab

    Detects PWA install state, getInstalledRelatedApps(), and service worker availability. Validates an origin pair against the current migration handshake: destination migrate_from, old-origin allow_migration, optional migrate_to, and redirect-safe install_url.

why it shipped

Installed PWAs bind their identity — permissions, home screen placement, session data — tightly to their web origin. When a company rebrands, restructures domains, or migrates infrastructure, this binding became a painful break: the old app had to be abandoned and users nudged to reinstall from scratch. PWA origin migration introduces a two-way handshake: the destination manifest names the predecessor with migrate_from, and the old origin confirms the relationship in /.well-known/web-app-origin-association with allow_migration. Chrome can then transfer the installed app's identity transparently, letting users continue using the app without a manual reinstall.

references

implementation reference

Need the exact API surface, compatibility boundaries, errors, lifecycle, and source links? Read the matching gendn reference ↗