v150 · PWA · Manifest Configuration

Manifest Configuration

The two files Chrome requires before migrating an installed PWA to a new same-site origin: the destination manifest with migrate_from, and the old origin's .well-known association file with allow_migration.

Both sides must opt in. The new origin's manifest declares which installed app it can replace; the old origin's well-known file grants that destination app ID permission to migrate. Chrome also requires a stable id in the destination manifest and currently limits the feature to same-site migrations.

required files

New origin — manifest.json

https://app.example.com/app/manifest.json

{
  "name": "My App",
  "id": "https://app.example.com/app/",
  "start_url": "/app/",
  "scope": "/app/",
  "migrate_from": [
    {
      "id": "https://www.example.com/app/",
      "behavior": "suggest"
    }
  ]
}

Old origin — well-known

https://www.example.com/.well-known/web-app-origin-association

{
  "https://app.example.com/app/": {
    "allow_migration": true
  }
}

field reference

Field	File	Required	Description
`id`	New manifest	Yes	Stable destination app ID. Chrome requires this so a `start_url` change does not create a split install.
`migrate_from[].id`	New manifest	Yes	The installed app ID on the old origin. A string shorthand is allowed, but an object also lets you set behavior and install URL.
`migrate_from[].behavior`	New manifest	Optional	`"suggest"` is passive and is the default; `"force"` blocks the next launch until the user migrates or uninstalls.
`migrate_from[].install_url`	New manifest	Optional	URL Chrome can fetch if the old app redirects and its old manifest is otherwise hard to discover during the update window.
`<new app id>.allow_migration`	Well-known	Yes	The old origin's explicit authorization for the destination app ID to migrate installs.
`migrate_to.id`	Old manifest	Optional	Proactive signal from the old app to the destination app ID, useful when the user might not visit the new origin first.

migration scenarios

Same-site subdomain move Old: www.example.com/app/ → New: app.example.com/app/. This matches Chrome 150's same-site limitation while changing the web origin.
Path cleanup with stable ID Old: example.com/social/ → New: social.example.com/. The destination manifest's id prevents the start URL change from creating a second app.
Redirect-backed migration Old URLs redirect to the new origin. Add install_url inside migrate_from so Chrome can still fetch a URL with the old manifest attached before migration completes.
Forced migration Set behavior: "force" only when users cannot continue using the old app. Chrome blocks launch until the user accepts the migration or uninstalls.

scenario focus

Select a scenario to focus its rendered example and summary.

implementation reference

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