@docusaurus/plugin-pwa 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/{sw.js → sw.ts}

@@ -6,11 +6,11 @@
  */
 /* eslint-disable no-restricted-globals */
 
-import {PrecacheController} from 'workbox-precaching';
+import {PrecacheController, type PrecacheEntry} from 'workbox-precaching';
 
 function parseSwParams() {
   const params = JSON.parse(
-    new URLSearchParams(self.location.search).get('params'),
+    new URLSearchParams(self.location.search).get('params')!,
   );
   if (params.debug) {
     console.log('[Docusaurus-PWA][SW]: Service Worker params:', params);
@@ -18,11 +18,11 @@ function parseSwParams() {
   return params;
 }
 
-// doc advise against dynamic imports in SW
+// Doc advises against dynamic imports in SW
 // https://developers.google.com/web/tools/workbox/guides/using-bundlers#code_splitting_and_dynamic_imports
 // https://twitter.com/sebastienlorber/status/1280155204575518720
-// but I think it's working fine as it's inlined by webpack, need to double check?
-async function runSWCustomCode(params) {
+// but looks it's working fine as it's inlined by webpack, need to double check
+async function runSWCustomCode(params: {offlineMode: boolean; debug: boolean}) {
   if (process.env.PWA_SW_CUSTOM) {
     const customSW = await import(process.env.PWA_SW_CUSTOM);
     if (typeof customSW.default === 'function') {
@@ -38,49 +38,43 @@ async function runSWCustomCode(params) {
 /**
  * Gets different possible variations for a request URL. Similar to
  * https://git.io/JvixK
- *
- * @param {string} url
  */
-function getPossibleURLs(url) {
-  const possibleURLs = [];
+function getPossibleURLs(url: string) {
   const urlObject = new URL(url, self.location.href);
 
   if (urlObject.origin !== self.location.origin) {
-    return possibleURLs;
+    return [];
   }
 
   // Ignore search params and hash
   urlObject.search = '';
   urlObject.hash = '';
 
-  // /blog.html
-  possibleURLs.push(urlObject.href);
-
-  // /blog/ => /blog/index.html
-  if (urlObject.pathname.endsWith('/')) {
-    possibleURLs.push(`${urlObject.href}index.html`);
-  } else {
+  return [
+    // /blog.html
+    urlObject.href,
+    // /blog/ => /blog/index.html
     // /blog => /blog/index.html
-    possibleURLs.push(`${urlObject.href}/index.html`);
-  }
-
-  return possibleURLs;
+    `${urlObject.href}${urlObject.pathname.endsWith('/') ? '' : '/'}index.html`,
+  ];
 }
 
 (async () => {
   const params = parseSwParams();
 
-  const precacheManifest = self.__WB_MANIFEST;
+  // eslint-disable-next-line no-underscore-dangle
+  const precacheManifest = (
+    self as typeof globalThis & {__WB_MANIFEST: (string | PrecacheEntry)[]}
+  ).__WB_MANIFEST;
   const controller = new PrecacheController({
-    fallbackToNetwork: true, // safer to turn this true?
+    // Safer to turn this true?
+    fallbackToNetwork: true,
   });
 
   if (params.offlineMode) {
     controller.addToCacheList(precacheManifest);
     if (params.debug) {
-      console.log('[Docusaurus-PWA][SW]: addToCacheList', {
-        precacheManifest,
-      });
+      console.log('[Docusaurus-PWA][SW]: addToCacheList', {precacheManifest});
     }
   }
 
@@ -88,31 +82,30 @@ function getPossibleURLs(url) {
 
   self.addEventListener('install', (event) => {
     if (params.debug) {
-      console.log('[Docusaurus-PWA][SW]: install event', {
-        event,
-      });
+      console.log('[Docusaurus-PWA][SW]: install event', {event});
     }
-    event.waitUntil(controller.install(event));
+    (event as ExtendableEvent).waitUntil(
+      controller.install(event as ExtendableEvent),
+    );
   });
 
   self.addEventListener('activate', (event) => {
     if (params.debug) {
-      console.log('[Docusaurus-PWA][SW]: activate event', {
-        event,
-      });
+      console.log('[Docusaurus-PWA][SW]: activate event', {event});
     }
-    event.waitUntil(controller.activate(event));
+    (event as ExtendableEvent).waitUntil(
+      controller.activate(event as ExtendableEvent),
+    );
   });
 
   self.addEventListener('fetch', async (event) => {
     if (params.offlineMode) {
-      const requestURL = event.request.url;
+      const requestURL = (event as FetchEvent).request.url;
       const possibleURLs = getPossibleURLs(requestURL);
-      for (let i = 0; i < possibleURLs.length; i += 1) {
-        const possibleURL = possibleURLs[i];
+      for (const possibleURL of possibleURLs) {
         const cacheKey = controller.getCacheKeyForURL(possibleURL);
         if (cacheKey) {
-          const cachedResponse = caches.match(cacheKey);
+          const cachedResponse = caches.match(cacheKey) as Promise<Response>;
           if (params.debug) {
             console.log('[Docusaurus-PWA][SW]: serving cached asset', {
               requestURL,
@@ -122,7 +115,7 @@ function getPossibleURLs(url) {
               cachedResponse,
             });
           }
-          event.respondWith(cachedResponse);
+          (event as FetchEvent).respondWith(cachedResponse);
           break;
         }
       }
@@ -131,15 +124,14 @@ function getPossibleURLs(url) {
 
   self.addEventListener('message', async (event) => {
     if (params.debug) {
-      console.log('[Docusaurus-PWA][SW]: message event', {
-        event,
-      });
+      console.log('[Docusaurus-PWA][SW]: message event', {event});
     }
 
-    const type = event.data && event.data.type;
+    const type = (event as MessageEvent).data?.type;
 
     if (type === 'SKIP_WAITING') {
-      self.skipWaiting();
+      // lib def bug, see https://github.com/microsoft/TypeScript/issues/14877
+      (self as typeof globalThis & ServiceWorkerGlobalScope).skipWaiting();
     }
   });
 })();

package/src/theme/PwaReloadPopup/index.tsx

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {useState} from 'react';
+import clsx from 'clsx';
+import Translate, {translate} from '@docusaurus/Translate';
+import type {Props} from '@theme/PwaReloadPopup';
+
+import styles from './styles.module.css';
+
+export default function PwaReloadPopup({onReload}: Props): JSX.Element | false {
+  const [isVisible, setIsVisible] = useState(true);
+
+  return (
+    isVisible && (
+      <div className={clsx('alert', 'alert--secondary', styles.popup)}>
+        <p>
+          <Translate
+            id="theme.PwaReloadPopup.info"
+            description="The text for PWA reload popup">
+            New version available
+          </Translate>
+        </p>
+        <div className={styles.buttonContainer}>
+          <button
+            className="button button--link"
+            type="button"
+            onClick={() => {
+              setIsVisible(false);
+              onReload();
+            }}>
+            <Translate
+              id="theme.PwaReloadPopup.refreshButtonText"
+              description="The text for PWA reload button">
+              Refresh
+            </Translate>
+          </button>
+
+          <button
+            aria-label={translate({
+              id: 'theme.PwaReloadPopup.closeButtonAriaLabel',
+              message: 'Close',
+              description:
+                'The ARIA label for close button of PWA reload popup',
+            })}
+            className="close"
+            type="button"
+            onClick={() => setIsVisible(false)}>
+            <span aria-hidden="true">×</span>
+          </button>
+        </div>
+      </div>
+    )
+  );
+}

package/src/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/// <reference types="@docusaurus/module-type-aliases" />

package/src/registerSw.js

@@ -1,303 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-import {createStorageSlot} from '@docusaurus/theme-common';
-
-// First: read the env variables (provided by Webpack)
-/* eslint-disable prefer-destructuring */
-const PWA_SERVICE_WORKER_URL = process.env.PWA_SERVICE_WORKER_URL;
-const PWA_RELOAD_POPUP = process.env.PWA_RELOAD_POPUP;
-const PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES =
-  process.env.PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES;
-const PWA_DEBUG = process.env.PWA_DEBUG;
-/* eslint-enable prefer-destructuring */
-
-const debug = PWA_DEBUG; // shortcut
-
-const MAX_MOBILE_WIDTH = 940;
-
-const AppInstalledEventFiredStorage = createStorageSlot(
-  'docusaurus.pwa.event.appInstalled.fired',
-);
-
-async function clearRegistrations() {
-  const registrations = await navigator.serviceWorker.getRegistrations();
-  if (debug) {
-    console.log(
-      `[Docusaurus-PWA][registerSw]: will unregister all service worker registrations`,
-      registrations,
-    );
-  }
-  await Promise.all(
-    registrations.map(async (registration) => {
-      const result = await registration?.registration?.unregister();
-      if (debug) {
-        console.log(
-          `[Docusaurus-PWA][registerSw]: unregister() service worker registration`,
-          registrations,
-          result,
-        );
-      }
-    }),
-  );
-  if (debug) {
-    console.log(
-      `[Docusaurus-PWA][registerSw]: unregistered all service worker registrations`,
-      registrations,
-    );
-  }
-  window.location.reload();
-}
-
-/*
-As of 2021:
-It is complicated and not very reliable to detect an app is actually installed.
-https://stackoverflow.com/questions/51735869/check-if-user-has-already-installed-pwa-to-homescreen-on-chrome
-
-- appinstalled event is not in the spec anymore and seems to not fire? https://firt.dev/pwa-2021#less-capabilities-%E2%98%B9%EF%B8%8F
-- getInstalledRelatedApps() is only supported in recent Chrome and does not seem to reliable either https://github.com/WICG/get-installed-related-apps
-- display-mode: standalone is not exactly the same concept, but looks like a decent fallback https://petelepage.com/blog/2019/07/is-my-pwa-installed/
- */
-async function isAppInstalledEventFired() {
-  return AppInstalledEventFiredStorage.get() === 'true';
-}
-async function isAppInstalledRelatedApps() {
-  if ('getInstalledRelatedApps' in window.navigator) {
-    const relatedApps = await navigator.getInstalledRelatedApps();
-    return relatedApps.some((app) => app.platform === 'webapp');
-  }
-  return false;
-}
-function isStandaloneDisplayMode() {
-  return window.matchMedia('(display-mode: standalone)').matches;
-}
-
-const OfflineModeActivationStrategiesImplementations = {
-  always: () => true,
-  mobile: () => window.innerWidth <= MAX_MOBILE_WIDTH,
-  saveData: () => !!(navigator.connection && navigator.connection.saveData),
-  appInstalled: async () => {
-    const installedEventFired = await isAppInstalledEventFired();
-    const installedRelatedApps = await isAppInstalledRelatedApps();
-    return installedEventFired || installedRelatedApps;
-  },
-  standalone: () => isStandaloneDisplayMode(),
-  queryString: () =>
-    new URLSearchParams(window.location.search).get('offlineMode') === 'true',
-};
-
-async function isStrategyActive(strategyName) {
-  return OfflineModeActivationStrategiesImplementations[strategyName]();
-}
-
-async function getActiveStrategies() {
-  const activeStrategies = await Promise.all(
-    PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES.map(async (strategyName) => {
-      const isActive = await isStrategyActive(strategyName);
-      return isActive ? strategyName : undefined;
-    }),
-  );
-  return activeStrategies.filter(Boolean); // remove undefined values
-}
-
-async function isOfflineModeEnabled() {
-  const activeStrategies = await getActiveStrategies();
-  const enabled = activeStrategies.length > 0;
-  if (debug) {
-    const logObject = {
-      activeStrategies,
-      availableStrategies: PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES,
-    };
-    if (enabled) {
-      console.log(
-        '[Docusaurus-PWA][registerSw]: offline mode enabled, because of activation strategies',
-        logObject,
-      );
-    } else {
-      console.log(
-        '[Docusaurus-PWA][registerSw]: offline mode disabled, because none of the offlineModeActivationStrategies could be used',
-        logObject,
-      );
-    }
-  }
-  return enabled;
-}
-
-function createServiceWorkerUrl(params) {
-  const paramsQueryString = JSON.stringify(params);
-  const url = `${PWA_SERVICE_WORKER_URL}?params=${encodeURIComponent(
-    paramsQueryString,
-  )}`;
-  if (debug) {
-    console.log(`[Docusaurus-PWA][registerSw]: service worker url`, {
-      url,
-      params,
-    });
-  }
-  return url;
-}
-
-async function registerSW() {
-  const {Workbox} = await import('workbox-window');
-
-  const offlineMode = await isOfflineModeEnabled();
-
-  const url = createServiceWorkerUrl({offlineMode, debug});
-  const wb = new Workbox(url);
-
-  const registration = await wb.register();
-
-  const sendSkipWaiting = () => wb.messageSW({type: 'SKIP_WAITING'});
-
-  const handleServiceWorkerWaiting = async () => {
-    if (debug) {
-      console.log('[Docusaurus-PWA][registerSw]: handleServiceWorkerWaiting');
-    }
-    // Immediately load new service worker when files aren't cached
-    if (!offlineMode) {
-      sendSkipWaiting();
-    } else if (PWA_RELOAD_POPUP) {
-      const renderReloadPopup = (await import('./renderReloadPopup')).default;
-      await renderReloadPopup({
-        onReload() {
-          wb.addEventListener('controlling', () => {
-            window.location.reload();
-          });
-          sendSkipWaiting();
-        },
-      });
-    }
-  };
-
-  if (debug) {
-    if (registration.active) {
-      console.log(
-        '[Docusaurus-PWA][registerSw]: registration.active',
-        registration,
-      );
-    }
-    if (registration.installing) {
-      console.log(
-        '[Docusaurus-PWA][registerSw]: registration.installing',
-        registration,
-      );
-    }
-    if (registration.waiting) {
-      console.log(
-        '[Docusaurus-PWA][registerSw]: registration.waiting',
-        registration,
-      );
-    }
-  }
-
-  // Update the current service worker when the next one has finished
-  // installing and transitions to waiting state.
-  wb.addEventListener('waiting', (event) => {
-    if (debug) {
-      console.log('[Docusaurus-PWA][registerSw]: event waiting', event);
-    }
-    handleServiceWorkerWaiting();
-  });
-
-  // Update current service worker if the next one finishes installing and
-  // moves to waiting state in another tab.
-  wb.addEventListener('externalwaiting', (event) => {
-    if (debug) {
-      console.log('[Docusaurus-PWA][registerSw]: event externalwaiting', event);
-    }
-    handleServiceWorkerWaiting();
-  });
-
-  // Update service worker if the next one is already in the waiting state.
-  // This happens when the user doesn't click on `reload` in the popup.
-  if (registration.waiting) {
-    await handleServiceWorkerWaiting();
-  }
-}
-
-// TODO these events still works in chrome but have been removed from the spec in 2019!
-// See https://github.com/w3c/manifest/pull/836
-function addLegacyAppInstalledEventsListeners() {
-  if (typeof window !== 'undefined') {
-    if (debug) {
-      console.log(
-        '[Docusaurus-PWA][registerSw]: addLegacyAppInstalledEventsListeners',
-      );
-    }
-
-    window.addEventListener('appinstalled', async (event) => {
-      if (debug) {
-        console.log('[Docusaurus-PWA][registerSw]: event appinstalled', event);
-      }
-
-      AppInstalledEventFiredStorage.set('true');
-      if (debug) {
-        console.log(
-          "[Docusaurus-PWA][registerSw]: AppInstalledEventFiredStorage.set('true')",
-        );
-      }
-
-      // After the app is installed, we register a service worker with the path
-      // `/sw?enabled`. Since the previous service worker was `/sw`, it'll be
-      // treated as a new one. The previous registration will need to be
-      // cleared, otherwise the reload popup will show.
-      await clearRegistrations();
-    });
-
-    // TODO this event still works in chrome but has been removed from the spec in 2019!!!
-    window.addEventListener('beforeinstallprompt', async (event) => {
-      if (debug) {
-        console.log(
-          '[Docusaurus-PWA][registerSw]: event beforeinstallprompt',
-          event,
-        );
-      }
-      // TODO instead of default browser install UI, show custom docusaurus prompt?
-      // event.preventDefault();
-      if (debug) {
-        console.log(
-          '[Docusaurus-PWA][registerSw]: AppInstalledEventFiredStorage.get()',
-          AppInstalledEventFiredStorage.get(),
-        );
-      }
-      if (AppInstalledEventFiredStorage.get()) {
-        AppInstalledEventFiredStorage.del();
-        if (debug) {
-          console.log(
-            '[Docusaurus-PWA][registerSw]: AppInstalledEventFiredStorage.del()',
-          );
-        }
-        // After uninstalling the app, if the user doesn't clear all data, then
-        // the previous service worker will continue serving cached files. We
-        // need to clear registrations and reload, otherwise the popup will show.
-        await clearRegistrations();
-      }
-    });
-
-    if (debug) {
-      console.log(
-        '[Docusaurus-PWA][registerSw]: legacy appinstalled and beforeinstallprompt event listeners installed',
-      );
-    }
-  }
-}
-
-/*
-Init code to run on the client!
- */
-if (typeof window !== 'undefined') {
-  if (debug) {
-    console.log('[Docusaurus-PWA][registerSw]: debug mode enabled');
-  }
-
-  if ('serviceWorker' in navigator) {
-    // First: add the listeners asap/synchronously
-    addLegacyAppInstalledEventsListeners();
-
-    // Then try to register the SW using lazy/dynamic imports
-    registerSW().catch((e) => console.error('registerSW failed', e));
-  }
-}