v148 · PWA · demo

Migration Timeline

Walk through each stage of a PWA origin migration — from the developer publishing the manifest declarations to Chrome silently updating the installed app on the user's device.

Step 0 of 6 — press Next to begin
①
Developer · old origin
Add migration declaration to old manifest
The developer adds a migration.new_origin field to app.oldexample.com/manifest.json, pointing to the new app URL. This is the outgoing signal.
// app.oldexample.com/manifest.json { "name": "My Great App", "migration": { "new_origin": "https://app.newexample.com" } }
②
Developer · new origin
Add confirmation to new manifest
The new origin must confirm it accepts the migration by declaring migration.old_origin. Chrome requires both sides — a one-sided claim is ignored for security.
// app.newexample.com/manifest.json { "name": "My Great App", "migration": { "old_origin": "https://app.oldexample.com" } }
③
Browser · background
User launches installed app from old origin
The user has the PWA installed at app.oldexample.com. When they launch it, Chrome fetches the manifest as part of its normal update check cycle.
// Chrome internally: // 1. Fetch app.oldexample.com/manifest.json // 2. Find manifest.migration.new_origin // → "https://app.newexample.com" // → initiate migration check
④
Browser · validation
Browser fetches new origin manifest and validates
Chrome fetches the new origin's manifest and checks migration.old_origin. It also verifies the same-site constraint — both origins must share a registrable domain.
// Chrome internally: // 1. Fetch app.newexample.com/manifest.json // 2. Check migration.old_origin === // "https://app.oldexample.com" ✓ // 3. Check same-site (both: example.com) ✓ // 4. Check HTTPS on both origins ✓ // → validation passed
⑤
Browser · update
Chrome transfers the installed app identity
The browser silently updates the installed app record to point to the new origin. The app icon, name, and position on the home screen / taskbar are preserved. No user prompt required.
// Result in browser's app registry: // Before: { origin: "app.oldexample.com", name: "My Great App" } // After: { origin: "app.newexample.com", name: "My Great App" } // // Home screen icon unchanged ✓ // Permissions preserved ✓ // No reinstall needed ✓
⑥
User experience
User opens app — now served from new origin
Next time the user taps the app icon, Chrome loads the new origin transparently. The user sees no change — same icon, same name, same experience. The migration is complete.
// User perspective: nothing changed // Developer perspective: app now at new origin // Old origin can redirect or sunset gracefully

see also