@docusaurus/plugin-pwa 0.0.0-4727 → 0.0.0-4731

package/lib/index.js

@@ -49,7 +49,7 @@ function pluginPWA(context, options) {
             return '../src/theme';
         },
         getClientModules() {
-            return isProd ? [swRegister] : [];
+            return isProd && swRegister ? [swRegister] : [];
         },
         getDefaultCodeTranslationMessages() {
             return (0, theme_translations_1.readDefaultCodeTranslationMessages)({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-pwa",
-  "version": "0.0.0-4727",
+  "version": "0.0.0-4731",
   "description": "Docusaurus Plugin to add PWA support.",
   "main": "lib/index.js",
   "types": "src/plugin-pwa.d.ts",
@@ -22,11 +22,11 @@
   "dependencies": {
     "@babel/core": "^7.17.7",
     "@babel/preset-env": "^7.16.11",
-    "@docusaurus/core": "0.0.0-4727",
-    "@docusaurus/theme-common": "0.0.0-4727",
-    "@docusaurus/theme-translations": "0.0.0-4727",
-    "@docusaurus/utils": "0.0.0-4727",
-    "@docusaurus/utils-validation": "0.0.0-4727",
+    "@docusaurus/core": "0.0.0-4731",
+    "@docusaurus/theme-common": "0.0.0-4731",
+    "@docusaurus/theme-translations": "0.0.0-4731",
+    "@docusaurus/utils": "0.0.0-4731",
+    "@docusaurus/utils-validation": "0.0.0-4731",
     "babel-loader": "^8.2.3",
     "clsx": "^1.1.1",
     "core-js": "^3.21.1",
@@ -39,12 +39,12 @@
     "workbox-window": "^6.5.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4727",
+    "@docusaurus/module-type-aliases": "0.0.0-4731",
     "fs-extra": "^10.0.1"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
-  "gitHead": "967bfff81002933a1c68980300233e0320398e04"
+  "gitHead": "f3787c5cd81d0d934005814e3038d897f5ba58aa"
 }

package/src/index.ts

@@ -71,7 +71,7 @@ export default function pluginPWA(
     },
 
     getClientModules() {
-      return isProd ? [swRegister] : [];
+      return isProd && swRegister ? [swRegister] : [];
     },
 
     getDefaultCodeTranslationMessages() {

package/src/plugin-pwa.d.ts

@@ -6,26 +6,90 @@
  */
 
 declare module '@docusaurus/plugin-pwa' {
-  export type pwaHead = {
-    tagName: string;
-    href?: string;
-    content?: string;
-    [attributeName: string]: string | boolean;
-  };
+  import type {InjectManifestOptions} from 'workbox-build';
 
   export type PluginOptions = {
+    /**
+     * Turn debug mode on:
+     *
+     * - Workbox logs
+     * - Additional Docusaurus logs
+     * - Unoptimized SW file output
+     * - Source maps
+     */
     debug?: boolean;
-    offlineModeActivationStrategies;
-    injectManifestConfig;
-    reloadPopup;
-    pwaHead: pwaHead[];
-    swCustom;
-    swRegister;
+    /**
+     * Strategies used to turn the offline mode on:
+     *
+     * - `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`
+     * - `always`: activates for all users
+     */
+    offlineModeActivationStrategies: (
+      | 'appInstalled'
+      | 'queryString'
+      | 'standalone'
+      | 'mobile'
+      | 'saveData'
+      | 'always'
+    )[];
+    /**
+     * Workbox options to pass to `workbox.injectManifest()`. This gives you
+     * control over which assets will be precached, and be available offline.
+     * @see https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.injectManifest
+     */
+    injectManifestConfig: InjectManifestOptions;
+    /**
+     * Module path to reload popup component. This popup is rendered when a new
+     * service worker is waiting to be installed, and we suggest a reload to
+     * the user.
+     *
+     * Passing `false` will disable the popup, but this is not recommended:
+     * users won't have a way to get up-to-date content.
+     * @see {@link @theme/PwaReloadPopup}
+     */
+    reloadPopup: string | false;
+    /**
+     * Array of objects containing `tagName` and key-value pairs for attributes
+     * to inject into the `<head>` tag. Technically you can inject any head tag
+     * through this, but it's ideally used for tags to make your site PWA-
+     * compliant.
+     */
+    pwaHead: {
+      tagName: string;
+      href?: string;
+      content?: string;
+      [attributeName: string]: string | boolean;
+    }[];
+    /**
+     * Useful for additional Workbox rules. You can do whatever a service worker
+     * can do here, and use the full power of workbox libraries. The code is
+     * transpiled, so you can use modern ES6+ syntax here.
+     */
+    swCustom?: string;
+    /**
+     * 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.
+     */
+    swRegister: string | false;
   };
 }
 
 declare module '@theme/PwaReloadPopup' {
   export interface Props {
+    /**
+     * The popup should call this callback when the `reload` button is clicked.
+     * This will tell the service worker to install the waiting service worker
+     * and reload the page.
+     */
     readonly onReload: () => void;
   }
   export default function PwaReloadPopup(props: Props): JSX.Element;