![Pete LePage](https://web.dev/images/authors/petelepage.jpg) Pete LePage [X](https://twitter.com/petele) [GitHub](https://github.com/petele) [Mastodon](https://techhub.social/@petele) [Homepage](https://petelepage.com/)

<br />

When the user installs your PWA, the browser needs a way to uniquely identify
the PWA. But, until recently, the web app manifest spec didn't explicitly
define a way to uniquely identify a PWA, leaving browsers to decide and
leading to different implementations. In some browsers, the `start_url`
is used, while in others, the path to the manifest file is used, making it
impossible to update either of those fields.

To solve this issue, there's a new optional `id` property in the web app
manifest spec, that allows you to explicitly define the identifier used for
your PWA. Adding the `id` property to the manifest removes the dependency on
the `start_url` or the location of the manifest, and makes it possible for
them to be updated in the future.

## What does the `id` property do?

The `id` property represents the identity of the PWA to the browser. When
the browser sees a manifest that does not have an identity that matches an
already installed PWA, it will treat it as a new PWA, even if it is served
from the same URL as another PWA. But if it sees a manifest with an identity
that matches the already installed PWA, it will treat that as the installed PWA.

## Browser support

Support for the `id` property landed in Chrome 96.

## What should I do if I have an app without an `id`?

There is **nothing you need to do** , and nothing will break if you
don't add an `id` to your web app manifest (as long as the `start_url` and
the manifest path remains the same). To future-proof your PWA, you can add
an `id` property to your web app manifest.

## How do I determine and set my `id`?

The safest, and the most accurate, way to determine the `id` for a PWA
is to check the value calculated by Chrome.

1. Using Chrome 96 or higher, open the **Manifest** pane of the **Application** panel in DevTools.
2. A note below the **Computed App Id** property will appear when the `id` is **not** specified in the web app manifest file.
3. Copy the `id` value shown in the note (see screenshot below).
4. Add an `id` property to the web app manifest using the `id` value shown in the note.

![Computed App Id in DevTools Application panel.](https://developer.chrome.com/static/docs/capabilities/pwa-manifest-id/image/note-showing-id-value.png)

```json
{
  ...
  id: "/?homescreen=1",
  start_url: "/?homescreen=1",
  ...
}
```

> [!CAUTION]
> **Caution:** In some cases, the `id` may not be the same as the `start_url`, therefore it is always **best** to verify the actual `id` value generated by Chrome in DevTools.

## What if I don't set an `id`?

**Don't worry, nothing will break** . Starting in Chrome 96, the
browser will generate an `id` if there is not one in the manifest
based on the `start_url` in the web app manifest.

Adding an `id` to the web app manifest makes it possible
to change the `start_url` and the manifest path (if and only if their particular
[origin](https://developer.mozilla.org/docs/Glossary/Origin) stays the same!),
because the browser will
identify the PWA based on the specified `id`, rather than the `start_url` or
manifest path.

## How do I test this?

To test the behavior, follow
these steps:

1. Install the PWA.
2. Open `about://web-app-internals/` and check the `manifest_id` and `start_url` property for the installed PWA.
3. Add an `id` property to your web app manifest following the steps in [How do I determine and set my `id`](https://developer.chrome.com/docs/capabilities/pwa-manifest-id.md.txt#determine-id) above.
4. Restart the browser using `chrome://restart`, launch the PWA from `about://apps`, then close the PWA to force the manifest file to refresh.
5. Open `about://web-app-internals/` and check the `manifest_id` property for the installed PWA to verify it hasn't changed.
6. Change the `start_url` in the web app manifest.
7. Restart the browser using `chrome://restart`, launch the PWA from `about://apps`, then close the PWA to force the manifest file to refresh.
8. Open `about://web-app-internals/` and check the `start_url` property for the installed PWA to verify it has been updated as expected.

## Additional resources

- [Explainer](https://github.com/philloooo/pwa-unique-id/blob/main/explainer.md)
- [Design doc](https://docs.google.com/document/u/2/d/1f9xQR1msTxiYvzFguKMkqSfrXMo_cT2yvhCEM3SYIt0/preview)
- [`id` property in Editor's draft of the Manifest spec](https://w3c.github.io/manifest/#id-member)