PWA origin migration

concepts

1. Migration Demo

   Inspects the current install context and explains which manifest and well-known fields Chrome uses when an installed PWA declares an origin migration.

2. Manifest Configuration

   Reference for the manifest fields that enable origin migration: id, migrate_from, optional migrate_to, and the old origin's allow_migration confirmation.

3. Manifest Builder

   Fill in your new and old origins to generate the destination manifest.json with migrate_from, the old origin's /.well-known/web-app-origin-association, and an optional old-manifest migrate_to hint.

4. Verification Checker

   Enter old and new origins and click "Run verification checklist" to walk through the Chrome 150 checks: HTTPS, same-site boundaries, destination id, migrate_from, allow_migration, behavior choice, and old-origin reachability.

5. Install State Simulator

   Four-phase walkthrough of a complete origin migration from the user's perspective: pre-migration install, developer deploy, Chrome's verification and user-visible migration step, and post-migration state. Each phase lists actor-tagged steps (Chrome / User / Server) and a data survival table showing what persists after migration.

6. Data Persistence Guide

   Chrome 150 preserves the install shortcut — but what about stored data? A comprehensive table covering 12 storage types (IndexedDB, localStorage, cookies, Cache API, push subscriptions, OPFS, WebAuthn passkeys, device permissions) with "auto-preserved", "requires action", or "lost / re-request" status for each. Includes a step-by-step IndexedDB migration code pattern for the most complex case.

   Storage Migration guide Data survival

why it shipped

Organisations move PWAs between same-site origins as products are restructured, for example from www.example.com/social to social.example.com. Previously, any origin change meant a new install path. Chrome 150 introduces a secure handshake: the new origin points back to the old app, the old origin authorizes the handoff, and Chrome can migrate the existing install after user-visible review or a forced migration flow.

the change

// New origin's manifest.json — declares the installed predecessor
{
  "name": "My App",
  "short_name": "MyApp",
  "id": "https://app.example.com/app/",
  "start_url": "/app/",
  "scope": "/app/",
  "migrate_from": [
    {
      "id": "https://www.example.com/app/",
      "behavior": "suggest"
    }
  ]
}

// Old origin confirms the migration:
// https://www.example.com/.well-known/web-app-origin-association
{
  "https://app.example.com/app/": {
    "allow_migration": true
  }
}

references

• ChromeStatus entry
• Chrome Developers — Seamless PWA origin migration
• MDN — Progressive Web Apps