diff --git a/microsoft-edge/devtools/progressive-web-apps/index-images/app-available-install-button.png b/microsoft-edge/devtools/progressive-web-apps/index-images/app-available-install-button.png new file mode 100644 index 0000000000..6d19cd1486 Binary files /dev/null and b/microsoft-edge/devtools/progressive-web-apps/index-images/app-available-install-button.png differ diff --git a/microsoft-edge/devtools/progressive-web-apps/index-images/app-available-install-icon.png b/microsoft-edge/devtools/progressive-web-apps/index-images/app-available-install-icon.png new file mode 100644 index 0000000000..52b29957bf Binary files /dev/null and b/microsoft-edge/devtools/progressive-web-apps/index-images/app-available-install-icon.png differ diff --git a/microsoft-edge/devtools/progressive-web-apps/index-images/screenshots-populating-the-installation-dialog.png b/microsoft-edge/devtools/progressive-web-apps/index-images/screenshots-populating-the-installation-dialog.png new file mode 100644 index 0000000000..d8b209408e Binary files /dev/null and b/microsoft-edge/devtools/progressive-web-apps/index-images/screenshots-populating-the-installation-dialog.png differ diff --git a/microsoft-edge/devtools/progressive-web-apps/index-images/shortcut-sections.png b/microsoft-edge/devtools/progressive-web-apps/index-images/shortcut-sections.png new file mode 100644 index 0000000000..4f1de5d522 Binary files /dev/null and b/microsoft-edge/devtools/progressive-web-apps/index-images/shortcut-sections.png differ diff --git a/microsoft-edge/devtools/progressive-web-apps/index-images/three-dot-menu.png b/microsoft-edge/devtools/progressive-web-apps/index-images/three-dot-menu.png new file mode 100644 index 0000000000..d3ca16d0b4 Binary files /dev/null and b/microsoft-edge/devtools/progressive-web-apps/index-images/three-dot-menu.png differ diff --git a/microsoft-edge/devtools/progressive-web-apps/index-images/viewing-minimum-safe-area.png b/microsoft-edge/devtools/progressive-web-apps/index-images/viewing-minimum-safe-area.png new file mode 100644 index 0000000000..6f3fd4d341 Binary files /dev/null and b/microsoft-edge/devtools/progressive-web-apps/index-images/viewing-minimum-safe-area.png differ diff --git a/microsoft-edge/devtools/progressive-web-apps/index.md b/microsoft-edge/devtools/progressive-web-apps/index.md index d8da30a8bf..a6c8fbb5ed 100644 --- a/microsoft-edge/devtools/progressive-web-apps/index.md +++ b/microsoft-edge/devtools/progressive-web-apps/index.md @@ -6,7 +6,7 @@ ms.author: msedgedevrel ms.topic: article ms.service: microsoft-edge ms.subservice: devtools -ms.date: 04/02/2026 +ms.date: 06/23/2026 --- # Debug a Progressive Web App (PWA) + Use the **Application** tool to inspect, modify, and debug a PWA's web app manifests, service workers, and service worker caches. +**Detailed contents:** +* [Introduction](#introduction) +* [Summary](#summary) +* [Web app manifest](#web-app-manifest) + * [View and check maskable icons](#view-and-check-maskable-icons) + * [Trigger installation](#trigger-installation) + * [Inspect shortcuts](#inspect-shortcuts) + * [Inspect screenshots for a richer installation UI](#inspect-screenshots-for-a-richer-installation-ui) + * [Test URL protocol handler registration](#test-url-protocol-handler-registration) +* [Service workers](#service-workers) +* [Display network requests handled by a service worker](#display-network-requests-handled-by-a-service-worker) +* [Service worker caches](#service-worker-caches) +* [Quota usage](#quota-usage) +* [Clear storage](#clear-storage) +* [Other Application tool guides](#other-application-tool-guides) +* [See also](#see-also) + + + +## Introduction + + +Progressive Web Apps (PWAs) are modern, high-quality applications built using web technology. PWAs offer similar capabilities to apps on iOS, Android, and desktop: + +* PWAs are reliable even in unstable network conditions. +* PWAs are installable to launch-surfaces of operating systems, such as: + * The **Applications** folder on Mac OS X. + * The **Start** menu on Windows. + * The home screen on Android and iOS. +* PWAs show up in: + * Activity switchers. + * Device search engines such as Spotlight. + * In content sharing sheets (todo: clarify). + +The features that are discussed below are features of the **Application** tool are relevant for PWAs. For help on the other features and panes in the **Application** tool, see: +* [Other Application tool guides](#other-application-tool-guides), below. +* [View the resource files that make up a webpage](../resources/index.md) +* [View and edit local storage](../storage/localstorage.md) + +See also: +* [Progressive Web Apps](https://web.dev/progressive-web-apps) at web.dev. +* [Overview of Progressive Web Apps (PWAs)](../../progressive-web-apps/index.md) + - +## Summary -The ![Application icon](./index-images/application-icon.png) **Application** tool includes the following panes for PWA features: +The ![Application icon](./index-images/application-icon.png) **Application** tool includes the following panes (accessed via the tree on the left) that cover PWA features: * Use the **Manifest** pane to inspect your web app manifest. @@ -41,34 +85,31 @@ The ![Application icon](./index-images/application-icon.png) **Application** too * Going offline. * Stopping a service worker. -* Use the **Cache Storage** pane to view your service worker cache. - * Use the **Storage** pane to view how much data your app is storing on the device, and clear the stored data. -The features that are discussed below are features of the **Application** tool are relevant for PWAs. For help on the other features and panes in the **Application** tool, see: -* [View the resource files that make up a webpage](../resources/index.md) -* [View and edit local storage](../storage/localstorage.md) +* Use the **Cache storage** pane to view your service worker cache. -See also: -* [Overview of Progressive Web Apps (PWAs)](../../progressive-web-apps/index.md) +todo: create an added png showing these tree items of interest ## Web app manifest -If you want your users to be able to add your app to their mobile homescreens, you need a web app manifest. The manifest defines how the app appears on the homescreen, where to direct the user when launching from homescreen, and what the app looks like on launch. - - +Related guides: +* [Improve user experiences with a Web App Manifest] /web/fundamentals/web-app-manifest +* [Using App Install Banners] /web/fundamentals/app-install-banners - +todo: link to sections when available To inspect a manifest: -1. Go to the webpage that uses the manifest, such as [Airhorner.com](https://airhorner.com), in a new window or tab. +1. Go to the webpage that uses the manifest, such as [Airhorner.com](https://airhorner.com) (todo: PWAmp), in a new window or tab. 1. Right-click the webpage, and then select **Inspect**. @@ -80,7 +121,7 @@ To inspect a manifest: The **App Manifest** pane is displayed, where you can inspect the manifest: -![The App Manifest Pane](./index-images/manifest-pane.png) +![The App Manifest Pane](./index-images/manifest-pane.png) todo: from airhorn to pwamp The **App Manifest** pane contains the following sections: * Top section, containing the manifest link @@ -92,73 +133,170 @@ The **App Manifest** pane contains the following sections: * **Screenshot #1** * **Screenshot #2** -* To view the manifest source file, click the link below the **App Manifest** label. In the previous figure, that link is `manifest.json`, which opens `https://airhorner.com/manifest.json`, for [Airhorner.com](https://airhorner.com). - +* To view the manifest source file, click the link below the **App Manifest** label. In the previous figure, that link is `manifest.json`, which opens `https://airhorner.com/manifest.json` (todo: PWAmp), for [Airhorner.com](https://airhorner.com). + +* To simulate an "Add to home screen" event, click the **Add to home screen** button. Check out the next section for more information. * The **Identity** and **Presentation** sections display fields from the manifest source in a more user-friendly display. * The **Icons** section displays every icon that's been specified in the manifest. +See also: +* [Add a web app manifest](https://web.dev/add-manifest/) at web.dev. + + + +#### Simulate Add to home screen events + + +todo: is this section semi-dup w/ [Trigger installation](#trigger-installation) below? - +A web app can only be added to a home screen when the site is visited at least twice, with at least five minutes between visits. While developing or debugging your Add to home screen workflow, the criteria is potentially inconvenient. +The **Add to home screen** button on the **App Manifest** pane lets you simulate Add to home screen events whenever you want. - +You can test out this feature with the [Microsoft I/O 2016 progressive web app](https://events.alpahabet.com/io2016/), which has proper support for Add to home screen. Clicking **Add to home screen** while the app is open prompts Microsoft Edge to display the "add this site to your shelf" banner, which is the desktop equivalent of the "add to home screen" banner for mobile devices. - +![Add to desktop shelf] todo: io.png - +todo: this para is dup w/ below: - +> Keep the **Console** open in the **Quick View** panel at the bottom of DevTools while simulating Add to home screen events. The Console tells you if your manifest has any issues and logs other information about the Add to home screen lifecycle. --> - +todo: this para is dup w/ below: - +The **Add to home screen** feature cannot yet simulate the workflow for mobile devices. Notice how the "add to shelf" prompt was triggered in the screenshot above, even though DevTools is in Device Mode (Device Emulation). However, if you can successfully add your app to your desktop shelf, then it works for mobile, too. --> - +todo: rework content after sample app is created - +todo: this para is dup w/ below: +If you want to test out the genuine mobile experience, you can connect a real mobile device to DevTools via [remote debugging](/debug/remote-debugging/remote-debugging), and then click the **Add to home screen** button (on DevTools) to trigger the "add to home screen" prompt on the connected mobile device. - +todo: link to "remote debugging" sections when available + + + +#### View and check maskable icons - +The **Icons** section of the **Manifest** page of the **Application** tool displays all the icons of your application. In the **Icons** section, you can also check safe areas for maskable icons, which is the format of icons that adapt to platforms. + +To trim the icons so that only the minimum safe area is visible, select the **Show only the minimum safe area for maskable icons** checkbox: +![Viewing the minimum safe areas for maskable icons](./index-images/viewing-minimum-safe-area.png) + - +If your entire logo is visible in the safe area, the formatting is valid. + +See also: +* [Adaptive icon support in PWAs with maskable icons](https://web.dev/articles/maskable-icon) at web.dev. + + + +#### Trigger installation - +Microsoft Edge makes it possible for you to enable and promote the installation of your PWA directly within its user interface. + +See also: +* [How to provide your own in-app installation experience](https://web.dev/customize-install/) at web.dev. + +To trigger the installation flow of your PWA: + +1. Open the PWA's landing page in Microsoft Edge. For example, open the [PWAmp](https://microsoftedge.github.io/Demos/pwamp/) demo in a new window or tab. + +1. On the right side of the Address bar at the top, click the **App available. Install PWAmp music player** button. + + The **Install PWAmp music player app** dialog opens: + + ![The "App available, Install" button](./index-images/app-available-install-button.png) +1. Click the **Install** button. - + + +###### Monitor the Console tool in the Quick view panel + +It's recommended that you keep the DevTools **Console** tool open in the **Quick view** panel when you trigger installation. The **Console** tells you if your manifest has any issues, and logs other information about the installation lifecycle. + +The **Install app** feature cannot simulate the workflow for mobile devices. The desktop Microsoft Edge browser displays the installation button in the Address bar, even though (todo: even when?) DevTools is in [Device Mode](https://developer.chrome.com/docs/devtools/device-mode) (todo: true? is DevTools in Device Mode?) (todo: local link). However, if you can successfully add your app to your desktop, then the app will work for mobile, too. + + + +###### Test a mobile device + +If you want to test out the actual mobile experience, you can connect a mobile device to DevTools via [remote debugging](https://developer.chrome.com/docs/devtools/remote-debugging) (todo: local link). To trigger the installation on the connected mobile device, open the three-dot menu (![The three-dot menu icon](./index-images/three-dot-menu.png)), and then click **Install app**. + + + +#### Inspect shortcuts - +App shortcuts let you to provide quick access to a handful of common actions that users need frequently. + +To inspect the shortcuts that you defined in your [manifest file](https://web.dev/articles/app-shortcuts#define_app_shortcuts_in_the_web_app_manifest), scroll to the **Shortcut #N** sections of the **Manifest** page of the **Application** tool. The **Shortcut #N** sections are below the **Windows Control Overlay** section of the **Manifest** page: + +![Shortcut section in the Manifest tab](./index-images/shortcut-sections.png) todo: pwamp +The above screenshot is from the [Rowsie](https://rowsie.app) (todo: pwamp) demo page. For more examples of shortcuts, inspect the demo page. - +See also: +* [App shortcuts](https://web.dev/articles/app-shortcuts) at web.dev. + + + +#### Inspect screenshots for a richer installation UI - +When you add a description and a set of screenshots to your manifest file, your app gets a richer installation dialog. + +To inspect the screenshots, scroll down to the **Screenshot #N** sections of the **Manifest** page of the **Application** tool: + +![The installation dialog, and screenshots in the Manifest page](./index-images/screenshots-populating-the-installation-dialog.png) (todo: pwamp) + + +See also: +* [screenshots](https://web.dev/add-manifest#screenshots) in _Add a web app manifest_ at web.dev. - + +#### Test URL protocol handler registration - +todo: format, links, pngs - https://developer.chrome.com/docs/devtools/progressive-web-apps/#test-protocol-handler + +A PWA can handle links that use a specific protocol, for a more integrated experience. To learn how to create a handler, see [URL protocol handler registration for PWAs](https://developer.chrome.com/docs/web-platform/best-practices/url-protocol-handler) (todo: local link or mdn) + +To test your handler: + +1. [Open DevTools](https://developer.chrome.com/docs/devtools/open) (todo: give inline steps, or local link) on the landing page of your PWA. For example, check out the [URL protocol handler](https://chrome.dev/devtools-protocol-handler/) demo PWA. + +1. From the demo page, install the PWA. (todo: but there is no "app available, install" button in address bar for https://chrome.dev/devtools-protocol-handler/ ) + +1. Reload the app. + + The browser has now registered the PWA as a handler for the `web+coffee` protocol. + +1. In the **Application** > **Manifest** > **Protocol Handlers** section, enter the URL (todo: URL portion? URL suffix? URL path?) that you want the handler to test, and then click the **Test protocol** button: + + ![Testing the handler] ./index-images/testing-handler.png todo + + In this example, the handler can process `americano`, `chai`, and `latte-macchiato`. + + Microsoft Edge asks you if it can open the app. + +1. Click the **Open Protocol Handler** button: + + ![Open the app] open-protocol-handler.png todo + + The **Allow app to open web+coffee links?** dialog opens: + + ![Allow to handle links] allow-handle-links.png todo + +1. Click the **Allow** button. + + The handler processes the link. An image of a coffee cup is displayed in the app. @@ -167,20 +305,18 @@ The **Add to homescreen** button on the **App Manifest** pane lets you simulate Service workers are a fundamental technology in the web platform. Service workers are scripts that the browser runs in the background, separate from a webpage. Service worker scripts enable your app to access features that don't need a webpage or user interaction, such as push notifications, background sync, and offline experiences. - - - +Related guides: +* [Intro to Service Workers] /web/fundamentals/primers/service-worker +* [Push Notifications: Timely, Relevant, and Precise] /web/fundamentals/push-notifications +* [How Push Works] /web/fundamentals/push-notifications/how-push-works - +todo: link to sections when available The main place in DevTools to inspect and debug service workers is the **Service workers** pane in the ![Application icon](./index-images/application-icon.png) **Application** tool. To view service workers: -1. Go to a webpage, such as [Airhorner.com](https://airhorner.com), in a new window or tab. +1. Go to a webpage, such as [Airhorner.com](https://airhorner.com) (todo: PWAmp), in a new window or tab. 1. Right-click the webpage, and then select **Inspect**. @@ -192,9 +328,9 @@ To view service workers: The **Service workers** pane is displayed: -![The Service workers pane](./index-images/service-workers-pane.png) +![The Service workers pane](./index-images/service-workers-pane.png) (todo: latest ui has 'w'; can redo png) -* If a service worker is installed to the currently open page, then the service worker is listed in the **Service workers** pane. For example, in the previous figure, there is a service worker installed for the scope of `https://weather-pwa-sample.firebaseapp.com`. +* If a service worker is installed to the currently open page, then the service worker is listed in the **Service workers** pane. For example, in the previous figure, there is a service worker installed for the scope of `https://weather-pwa-sample.firebaseapp.com`. (todo: update when use PWAmp instead of Airhorner) * The **Offline** checkbox puts DevTools into offline mode. This is equivalent to the offline mode available from the ![Network icon](./index-images/network-icon.png) **Network** tool, or the `Go offline` option in the [Command Menu](../command-menu/index.md). @@ -228,15 +364,13 @@ To view service workers: * The **Update Cycle** table displays the service worker's activities and their elapsed times, such as **Install**, **Wait**, and **Activate**. To see the exact timestamp of each activity, click the **Expand** (![Expander triangle](./index-images/expander-icon.png)) buttons. -If the service worker causes any errors, an **Errors** label is displayed. +If the service worker causes any errors, an **Errors** label is displayed: - +![Service worker with errors] todo sw-error.png - +todo: capture "Service Worker Errors" sample when available - +todo: link Web "How tickle works" sections when available See also: * [Service Worker API](https://developer.mozilla.org/docs/Web/API/Service_Worker_API) - at MDN, about service workers. @@ -250,7 +384,7 @@ From the **Service workers** pane of the **Application** tool, you can quickly a To display the network requests that are handled by a service worker: -1. Go to a webpage, such as [Airhorner.com](https://airhorner.com), in a new window or tab. +1. Go to a webpage, such as [Airhorner.com](https://airhorner.com) (todo: PWAmp), in a new window or tab. 1. Right-click the webpage, and then select **Inspect**. @@ -298,41 +432,43 @@ All open caches are listed under the **Cache Storage** expander. Some responses within the **Cache Storage** pane may be flagged as being "opaque". This refers to a response retrieved from a different origin, like from a **CDN** or remote API, when [CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) isn't enabled. - +todo: link Web "CDN" section when available - +todo: link Web "opaque" section when available In order to avoid leakage of cross-domain information, significant padding is added to the size of an opaque response used for calculating storage quota limits (for example whether a `QuotaExceeded` exception is thrown) and reported by the `navigator.storage` API. - - +todo: link to Estimating "`navigator.storage` API" sections when available: +See also: +* [Estimating available storage space] whats-new/2017/08/estimating-available-storage-space The details of this padding vary from browser to browser, but for Microsoft Edge, this means that the **minimum size** that any single cached opaque response contributes to the overall storage usage is [approximately 7 megabytes](https://bugs.chromium.org/p/chromium/issues/detail?id=796060#c17). Remember the padding when determining how many opaque responses you want to cache, since you may easily exceed storage quota limitations much sooner than you otherwise expect based on the actual size of the opaque resources. Related Guides: * [Stack Overflow: What limitations apply to opaque responses?](https://stackoverflow.com/q/39109789/385997) - +* [Alphabet work container: Understanding Storage Quota] /web/tools/Alphabet-work-container/guides/storage-quota#beware_of_opaque_responses - todo - +todo: link Work container storage quota for opaque responses section when available ## Clear storage +todo: there's no longer a "Clear Storage" tab/pane, though upstream outdated section mentions it and links to an article about it, but that linked upstream article no longer says "the Clear Storage tab/pane" + The **Clear Storage** tab is useful when developing a progressive web app. Use the **Clear Storage** pane to unregister service workers and clear all caches and storage, with a single button-click. - ## Other Application tool guides - For the other panes of the ![Application icon](./index-images/application-icon.png) **Application** tool, see: * [Inspect page resources](/iterate/manage-data/page-resources) * [Inspect and manage local storage and caches](/iterate/manage-data/local-storage) - + +todo: link to the above sections when available