@docusaurus/plugin-pwa 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/lib/theme/PwaReloadPopup/styles.module.css

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+
+.popup {
+  position: fixed;
+  bottom: 16px;
+  right: 16px;
+  width: 344px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  z-index: 999;
+}
+
+.popup p {
+  margin: 0;
+}
+
+@media screen and (max-width: 500px) {
+  .popup {
+    width: 100%;
+    bottom: 0;
+    right: 0;
+  }
+}
+
+.buttonContainer {
+  display: flex;
+  align-items: center;
+}
+
+.buttonContainer :global(.close) {
+  margin: 0;
+  padding: 0;
+}

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@docusaurus/plugin-pwa",
-  "version": "2.0.0-beta.1ec2c95e3",
+  "version": "2.0.0-beta.21",
   "description": "Docusaurus Plugin to add PWA support.",
-  "main": "src/index.js",
+  "main": "lib/index.js",
+  "types": "src/plugin-pwa.d.ts",
+  "scripts": {
+    "build": "tsc --build && node ../../admin/scripts/copyUntypedFiles.js && prettier --config ../../.prettierrc --write \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -13,26 +20,34 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.12.13",
-    "@babel/plugin-proposal-optional-chaining": "^7.12.16",
-    "@babel/preset-env": "^7.12.16",
-    "@docusaurus/core": "2.0.0-beta.1ec2c95e3",
-    "@docusaurus/theme-common": "2.0.0-beta.1ec2c95e3",
-    "@docusaurus/utils-validation": "2.0.0-beta.1ec2c95e3",
-    "babel-loader": "^8.2.2",
+    "@babel/core": "^7.18.2",
+    "@babel/preset-env": "^7.18.2",
+    "@docusaurus/core": "2.0.0-beta.21",
+    "@docusaurus/theme-common": "2.0.0-beta.21",
+    "@docusaurus/theme-translations": "2.0.0-beta.21",
+    "@docusaurus/utils": "2.0.0-beta.21",
+    "@docusaurus/utils-validation": "2.0.0-beta.21",
+    "babel-loader": "^8.2.5",
     "clsx": "^1.1.1",
-    "core-js": "^2.6.5",
-    "terser-webpack-plugin": "^5.1.3",
-    "webpack": "^5.40.0",
-    "webpack-merge": "^5.7.3",
-    "workbox-build": "^6.1.1",
-    "workbox-precaching": "^6.1.1",
-    "workbox-window": "^6.1.1"
+    "core-js": "^3.22.7",
+    "terser-webpack-plugin": "^5.3.1",
+    "tslib": "^2.4.0",
+    "webpack": "^5.72.1",
+    "webpack-merge": "^5.8.0",
+    "workbox-build": "^6.5.3",
+    "workbox-precaching": "^6.5.3",
+    "workbox-window": "^6.5.3"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "fs-extra": "^10.1.0"
   },
   "peerDependencies": {
-    "@babel/core": "^7.0.0",
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
-  "gitHead": "05c1ed75bb06738f274fe71baf71749a05b2db24"
+  "engines": {
+    "node": ">=16.14"
+  },
+  "gitHead": "69ac49fc6909517f13615ee40290c4bd00c39df4"
 }

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

@@ -5,14 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const LogPlugin = require('@docusaurus/core/lib/webpack/plugins/LogPlugin')
-  .default;
-const {compile} = require('@docusaurus/core/lib/webpack/utils');
-const path = require('path');
-const webpack = require('webpack');
-const {injectManifest} = require('workbox-build');
-const {PluginOptionSchema} = require('./pluginOptionSchema');
-const Terser = require('terser-webpack-plugin');
+import path from 'path';
+import webpack, {type Configuration} from 'webpack';
+import Terser from 'terser-webpack-plugin';
+import {injectManifest} from 'workbox-build';
+import {normalizeUrl} from '@docusaurus/utils';
+import {compile} from '@docusaurus/core/lib/webpack/utils';
+import LogPlugin from '@docusaurus/core/lib/webpack/plugins/LogPlugin';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import type {HtmlTags, LoadContext, Plugin} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-pwa';
 
 const isProd = process.env.NODE_ENV === 'production';
 
@@ -33,22 +35,23 @@ function getSWBabelLoader() {
           },
         ],
       ],
-      plugins: [
-        require.resolve('@babel/plugin-proposal-object-rest-spread'),
-        require.resolve('@babel/plugin-proposal-optional-chaining'),
-        require.resolve('@babel/plugin-proposal-nullish-coalescing-operator'),
-      ],
     },
   };
 }
 
-function plugin(context, options) {
-  const {outDir, baseUrl} = context;
+export default function pluginPWA(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin<void> {
+  const {
+    outDir,
+    baseUrl,
+    i18n: {currentLocale},
+  } = context;
   const {
     debug,
     offlineModeActivationStrategies,
     injectManifestConfig,
-    reloadPopup,
     pwaHead,
     swCustom,
     swRegister,
@@ -58,11 +61,21 @@ function plugin(context, options) {
     name: 'docusaurus-plugin-pwa',
 
     getThemePath() {
-      return path.resolve(__dirname, './theme');
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
     },
 
     getClientModules() {
-      return isProd ? [swRegister] : [];
+      return isProd && swRegister ? [swRegister] : [];
+    },
+
+    getDefaultCodeTranslationMessages() {
+      return readDefaultCodeTranslationMessages({
+        locale: currentLocale,
+        name: 'plugin-pwa',
+      });
     },
 
     configureWebpack(config) {
@@ -75,25 +88,40 @@ function plugin(context, options) {
           new webpack.EnvironmentPlugin({
             PWA_DEBUG: debug,
             PWA_SERVICE_WORKER_URL: path.posix.resolve(
-              `${config.output.publicPath || '/'}`,
+              `${(config.output?.publicPath as string) || '/'}`,
               'sw.js',
             ),
-            PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES: offlineModeActivationStrategies,
-            PWA_RELOAD_POPUP: reloadPopup,
+            PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES:
+              offlineModeActivationStrategies,
           }),
         ],
       };
     },
 
     injectHtmlTags() {
-      const headTags = [];
-      if (isProd && pwaHead) {
-        pwaHead.forEach(({tagName, ...attributes}) =>
-          headTags.push({
+      const headTags: HtmlTags = [];
+      if (isProd) {
+        pwaHead.forEach(({tagName, ...attributes}) => {
+          (['href', 'content'] as const).forEach((attribute) => {
+            const attributeValue = attributes[attribute];
+
+            if (!attributeValue) {
+              return;
+            }
+
+            const attributePath =
+              !!path.extname(attributeValue) && attributeValue;
+
+            if (attributePath && !attributePath.startsWith(baseUrl)) {
+              attributes[attribute] = normalizeUrl([baseUrl, attributeValue]);
+            }
+          });
+
+          return headTags.push({
             tagName,
             attributes,
-          }),
-        );
+          });
+        });
       }
       return {headTags};
     },
@@ -105,8 +133,8 @@ function plugin(context, options) {
 
       const swSourceFileTest = /\.m?js$/;
 
-      const swWebpackConfig = {
-        entry: path.resolve(__dirname, 'sw.js'),
+      const swWebpackConfig: Configuration = {
+        entry: require.resolve('./sw.js'),
         output: {
           path: outDir,
           filename: 'sw.js',
@@ -118,17 +146,19 @@ function plugin(context, options) {
         optimization: {
           splitChunks: false,
           minimize: !debug,
-          // see https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack
-          minimizer: [
-            !debug &&
-              new Terser({
-                test: swSourceFileTest,
-              }),
-          ].filter(Boolean),
+          // See https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack
+          minimizer: debug
+            ? []
+            : [
+                new Terser({
+                  test: swSourceFileTest,
+                }),
+              ],
         },
         plugins: [
           new webpack.EnvironmentPlugin({
-            PWA_SW_CUSTOM: swCustom || '', // fallback value required with Webpack 5
+            // Fallback value required with Webpack 5
+            PWA_SW_CUSTOM: swCustom ?? '',
           }),
           new LogPlugin({
             name: 'Service Worker',
@@ -139,7 +169,7 @@ function plugin(context, options) {
           rules: [
             {
               test: swSourceFileTest,
-              exclude: /(node_modules)/,
+              exclude: /node_modules/,
               use: getSWBabelLoader(),
             },
           ],
@@ -156,9 +186,10 @@ function plugin(context, options) {
           '**/*.{js,json,css,html}',
           '**/*.{png,jpg,jpeg,gif,svg,ico}',
           '**/*.{woff,woff2,eot,ttf,otf}',
-          ...(injectManifest.globPatterns || []),
+          // @ts-expect-error: internal API?
+          ...((injectManifest.globPatterns as string[] | undefined) ?? []),
         ],
-        // those attributes are not overrideable
+        // Those attributes are not overrideable
         swDest,
         swSrc: swDest,
         globDirectory: props.outDir,
@@ -167,8 +198,4 @@ function plugin(context, options) {
   };
 }
 
-module.exports = plugin;
-
-plugin.validateOptions = function validateOptions({validate, options}) {
-  return validate(PluginOptionSchema, options);
-};
+export {validateOptions} from './options';

package/src/{pluginOptionSchema.js → options.ts}

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const {Joi} = require('@docusaurus/utils-validation');
-const path = require('path');
+import {Joi} from '@docusaurus/utils-validation';
+import type {OptionValidationContext} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-pwa';
 
 const DEFAULT_OPTIONS = {
   debug: false,
@@ -18,11 +19,10 @@ const DEFAULT_OPTIONS = {
   injectManifestConfig: {},
   pwaHead: [],
   swCustom: undefined,
-  swRegister: path.join(__dirname, 'registerSw.js'),
-  reloadPopup: '@theme/PwaReloadPopup',
+  swRegister: './registerSw.js',
 };
 
-exports.PluginOptionSchema = Joi.object({
+const optionsSchema = Joi.object<PluginOptions>({
   debug: Joi.bool().default(DEFAULT_OPTIONS.debug),
   offlineModeActivationStrategies: Joi.array()
     .items(
@@ -48,7 +48,16 @@ exports.PluginOptionSchema = Joi.object({
   swRegister: Joi.alternatives()
     .try(Joi.string(), Joi.bool().valid(false))
     .default(DEFAULT_OPTIONS.swRegister),
-  reloadPopup: Joi.alternatives()
-    .try(Joi.string(), Joi.bool().valid(false))
-    .default(DEFAULT_OPTIONS.reloadPopup),
+  // @ts-expect-error: forbidden
+  reloadPopup: Joi.any().forbidden().messages({
+    'any.unknown':
+      'The reloadPopup option is removed in favor of swizzling. See https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#customizing-reload-popup for how to customize the reload popup using swizzling.',
+  }),
 });
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<PluginOptions, PluginOptions>): PluginOptions {
+  return validate(optionsSchema, options);
+}

package/src/plugin-pwa.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+
+declare module '@docusaurus/plugin-pwa' {
+  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;
+    /**
+     * 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;
+    /**
+     * 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 | undefined;
+    }[];
+    /**
+     * 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;
+  };
+
+  export type Options = Partial<PluginOptions>;
+}
+
+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;
+}

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

@@ -4,18 +4,18 @@
  * 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_SERVICE_WORKER_URL = process.env.PWA_SERVICE_WORKER_URL!;
+const PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES = process.env
+  .PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES as unknown as (keyof typeof OfflineModeActivationStrategiesImplementations)[];
 const PWA_DEBUG = process.env.PWA_DEBUG;
 /* eslint-enable prefer-destructuring */
 
-const debug = PWA_DEBUG; // shortcut
+const debug = PWA_DEBUG; // Shortcut
 
 const MAX_MOBILE_WIDTH = 940;
 
@@ -33,7 +33,7 @@ async function clearRegistrations() {
   }
   await Promise.all(
     registrations.map(async (registration) => {
-      const result = await registration?.registration?.unregister();
+      const result = await registration.unregister();
       if (debug) {
         console.log(
           `[Docusaurus-PWA][registerSw]: unregister() service worker registration`,
@@ -64,6 +64,14 @@ https://stackoverflow.com/questions/51735869/check-if-user-has-already-installed
 async function isAppInstalledEventFired() {
   return AppInstalledEventFiredStorage.get() === 'true';
 }
+
+declare global {
+  interface Navigator {
+    getInstalledRelatedApps: () => Promise<{platform: string}[]>;
+    connection?: {effectiveType: string; saveData: boolean};
+  }
+}
+
 async function isAppInstalledRelatedApps() {
   if ('getInstalledRelatedApps' in window.navigator) {
     const relatedApps = await navigator.getInstalledRelatedApps();
@@ -78,7 +86,7 @@ function isStandaloneDisplayMode() {
 const OfflineModeActivationStrategiesImplementations = {
   always: () => true,
   mobile: () => window.innerWidth <= MAX_MOBILE_WIDTH,
-  saveData: () => !!(navigator.connection && navigator.connection.saveData),
+  saveData: () => !!navigator.connection?.saveData,
   appInstalled: async () => {
     const installedEventFired = await isAppInstalledEventFired();
     const installedRelatedApps = await isAppInstalledRelatedApps();
@@ -89,7 +97,9 @@ const OfflineModeActivationStrategiesImplementations = {
     new URLSearchParams(window.location.search).get('offlineMode') === 'true',
 };
 
-async function isStrategyActive(strategyName) {
+async function isStrategyActive(
+  strategyName: keyof typeof OfflineModeActivationStrategiesImplementations,
+) {
   return OfflineModeActivationStrategiesImplementations[strategyName]();
 }
 
@@ -100,7 +110,7 @@ async function getActiveStrategies() {
       return isActive ? strategyName : undefined;
     }),
   );
-  return activeStrategies.filter(Boolean); // remove undefined values
+  return activeStrategies.filter(Boolean);
 }
 
 async function isOfflineModeEnabled() {
@@ -126,7 +136,7 @@ async function isOfflineModeEnabled() {
   return enabled;
 }
 
-function createServiceWorkerUrl(params) {
+function createServiceWorkerUrl(params: object) {
   const paramsQueryString = JSON.stringify(params);
   const url = `${PWA_SERVICE_WORKER_URL}?params=${encodeURIComponent(
     paramsQueryString,
@@ -159,7 +169,7 @@ async function registerSW() {
     // Immediately load new service worker when files aren't cached
     if (!offlineMode) {
       sendSkipWaiting();
-    } else if (PWA_RELOAD_POPUP) {
+    } else {
       const renderReloadPopup = (await import('./renderReloadPopup')).default;
       await renderReloadPopup({
         onReload() {
@@ -172,7 +182,7 @@ async function registerSW() {
     }
   };
 
-  if (debug) {
+  if (debug && registration) {
     if (registration.active) {
       console.log(
         '[Docusaurus-PWA][registerSw]: registration.active',
@@ -204,6 +214,7 @@ async function registerSW() {
 
   // Update current service worker if the next one finishes installing and
   // moves to waiting state in another tab.
+  // @ts-expect-error: not present in the API typings anymore
   wb.addEventListener('externalwaiting', (event) => {
     if (debug) {
       console.log('[Docusaurus-PWA][registerSw]: event externalwaiting', event);
@@ -213,13 +224,13 @@ async function registerSW() {
 
   // 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) {
+  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
+// 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) {
@@ -247,7 +258,8 @@ function addLegacyAppInstalledEventsListeners() {
       await clearRegistrations();
     });
 
-    // TODO this event still works in chrome but has been removed from the spec in 2019!!!
+    // 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(
@@ -255,7 +267,8 @@ function addLegacyAppInstalledEventsListeners() {
           event,
         );
       }
-      // TODO instead of default browser install UI, show custom docusaurus prompt?
+      // TODO instead of default browser install UI, show custom docusaurus
+      // prompt?
       // event.preventDefault();
       if (debug) {
         console.log(
@@ -272,7 +285,7 @@ function addLegacyAppInstalledEventsListeners() {
         }
         // 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.
+        // need to clear registrations and reload, otherwise the popup shows.
         await clearRegistrations();
       }
     });
@@ -298,6 +311,6 @@ if (typeof window !== 'undefined') {
     addLegacyAppInstalledEventsListeners();
 
     // Then try to register the SW using lazy/dynamic imports
-    registerSW().catch((e) => console.error('registerSW failed', e));
+    registerSW().catch((e: unknown) => console.error('registerSW failed', e));
   }
 }

package/src/{renderReloadPopup.js → renderReloadPopup.tsx}

@@ -6,7 +6,8 @@
  */
 
 import React from 'react';
-import {render} from 'react-dom';
+import ReactDOM from 'react-dom';
+import type {Props} from '@theme/PwaReloadPopup';
 
 const POPUP_CONTAINER_ID = 'pwa-popup-container';
 
@@ -19,8 +20,8 @@ const createContainer = () => {
   return container;
 };
 
-export default async function renderReloadPopup(props) {
+export default async function renderReloadPopup(props: Props): Promise<void> {
   const container = getContainer() || createContainer();
-  const {default: ReloadPopup} = await import(process.env.PWA_RELOAD_POPUP);
-  render(<ReloadPopup {...props} />, container);
+  const ReloadPopup = (await import('@theme/PwaReloadPopup')).default;
+  ReactDOM.render(<ReloadPopup {...props} />, container);
 }