fix(v2): PWA issues + improve docs (#4377)

* debug pwa

* more debugging logs + attempt to upgrade workbox

* fix PWA ?

* fix PWA ?

* enable pwa debugging for deploy previews

* try to fix the  app installed issue?

* try to fix appinstalled not firing

* try to add related applications to the PWA manifest

* attempt to fix related_applications

* attempt to fix related_applications

* attempt to fix related_applications

* improve PWA strategies

* improve PWA doc

* refactor/cleanup registerSw

* cleanup

website/docs/api/plugins/plugin-pwa.md

@@ -25,7 +25,11 @@ module.exports = {
       '@docusaurus/plugin-pwa',
       {
         debug: true,
-        offlineModeActivationStrategies: ['appInstalled', 'queryString'],
+        offlineModeActivationStrategies: [
+          'appInstalled',
+          'standalone',
+          'queryString',
+        ],
         pwaHead: [
           {
             tagName: 'link',
@@ -63,6 +67,12 @@ If your browser supports it, you should be able to install a Docusaurus site as
 
 ![pwa_install.gif](/img/pwa_install.gif)
 
+:::note
+
+App installation requires the https protocol and a valid manifest.
+
+:::
+
 ## Offline mode (precaching)
 
 We enable users to browse a Docusaurus site offline, by using service-worker precaching.
@@ -102,11 +112,12 @@ Turn debug mode on:
 ### `offlineModeActivationStrategies`
 
 - Type: `Array<'appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always'>`
-- Default: `['appInstalled','queryString']`
+- Default: `['appInstalled','queryString','standalone']`
 
 Strategies used to turn the offline mode on:
 
-- `appInstalled`: activates for users having installed the site as an app
+- `appInstalled`: activates for users having installed the site as an app (not 100% reliable)
+- `standalone`: activates for users running the app as standalone (often the case once a PWA is installed)
 - `queryString`: activates if queryString contains `offlineMode=true` (convenient for PWA debugging)
 - `mobile`: activates for mobile users (width <= 940px)
 - `saveData`: activates for users with `navigator.connection.saveData === true`
@@ -118,6 +129,16 @@ Use this carefully: some users may not like to be forced to use the offline mode
 
 :::
 
+:::danger
+
+It is not possible to detect if an as a PWA in a very reliable way.
+
+The `appinstalled` event has been [removed from the specification](https://github.com/w3c/manifest/pull/836), and the [`navigator.getInstalledRelatedApps()`](https://web.dev/get-installed-related-apps/) API is only supported in recent Chrome versions and require `related_applications` declared in the manifest.
+
+The [`standalone` strategy](https://petelepage.com/blog/2019/07/is-my-pwa-installed/) is a nice fallback to activate the offline mode (at least when running the installed app).
+
+:::
+
 ### `injectManifestConfig`
 
 [Workbox options](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.injectManifest) to pass to `workbox.injectManifest()`. This gives you control over which assets will be precached, and be available offline.
@@ -278,3 +299,15 @@ The module should have a `default` function export, and receives some params.
 Adds an entry before the Docusaurus app so that registration can happen before the app runs. The default `registerSW.js` file is enough for simple registration.
 
 Passing `false` will disable registration entirely.
+
+## Manifest example
+
+The Docusaurus site manifest can serve as an inspiration:
+
+```mdx-code-block
+import CodeBlock from '@theme/CodeBlock';
+
+<CodeBlock className="language-json">
+  {JSON.stringify(require("@site/static/manifest.json"),null,2)}
+</CodeBlock>
+```