@docusaurus/plugin-pwa 2.0.0-beta.16 → 2.0.0-beta.19

package/lib/index.js

@@ -10,11 +10,11 @@ exports.validateOptions = void 0;
 const tslib_1 = require("tslib");
 const utils_1 = require("@docusaurus/utils");
 const utils_2 = require("@docusaurus/core/lib/webpack/utils");
-const LogPlugin_1 = (0, tslib_1.__importDefault)(require("@docusaurus/core/lib/webpack/plugins/LogPlugin"));
+const LogPlugin_1 = tslib_1.__importDefault(require("@docusaurus/core/lib/webpack/plugins/LogPlugin"));
 const theme_translations_1 = require("@docusaurus/theme-translations");
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
-const webpack_1 = (0, tslib_1.__importDefault)(require("webpack"));
-const terser_webpack_plugin_1 = (0, tslib_1.__importDefault)(require("terser-webpack-plugin"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const webpack_1 = tslib_1.__importDefault(require("webpack"));
+const terser_webpack_plugin_1 = tslib_1.__importDefault(require("terser-webpack-plugin"));
 const workbox_build_1 = require("workbox-build");
 const isProd = process.env.NODE_ENV === 'production';
 function getSWBabelLoader() {
@@ -43,13 +43,13 @@ function pluginPWA(context, options) {
     return {
         name: 'docusaurus-plugin-pwa',
         getThemePath() {
-            return path_1.default.resolve(__dirname, '../lib/theme');
+            return '../lib/theme';
         },
         getTypeScriptThemePath() {
-            return path_1.default.resolve(__dirname, '../src/theme');
+            return '../src/theme';
         },
         getClientModules() {
-            return isProd ? [swRegister] : [];
+            return isProd && swRegister ? [swRegister] : [];
         },
         getDefaultCodeTranslationMessages() {
             return (0, theme_translations_1.readDefaultCodeTranslationMessages)({
@@ -58,7 +58,6 @@ function pluginPWA(context, options) {
             });
         },
         configureWebpack(config) {
-            var _a;
             if (!isProd) {
                 return {};
             }
@@ -66,7 +65,7 @@ function pluginPWA(context, options) {
                 plugins: [
                     new webpack_1.default.EnvironmentPlugin({
                         PWA_DEBUG: debug,
-                        PWA_SERVICE_WORKER_URL: path_1.default.posix.resolve(`${((_a = config.output) === null || _a === void 0 ? void 0 : _a.publicPath) || '/'}`, 'sw.js'),
+                        PWA_SERVICE_WORKER_URL: path_1.default.posix.resolve(`${config.output?.publicPath || '/'}`, 'sw.js'),
                         PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES: offlineModeActivationStrategies,
                         PWA_RELOAD_POPUP: reloadPopup,
                     }),
@@ -101,7 +100,7 @@ function pluginPWA(context, options) {
             }
             const swSourceFileTest = /\.m?js$/;
             const swWebpackConfig = {
-                entry: path_1.default.resolve(__dirname, 'sw.js'),
+                entry: require.resolve('./sw.js'),
                 output: {
                     path: outDir,
                     filename: 'sw.js',
@@ -113,7 +112,7 @@ function pluginPWA(context, options) {
                 optimization: {
                     splitChunks: false,
                     minimize: !debug,
-                    // see https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack
+                    // See https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack
                     minimizer: debug
                         ? []
                         : [
@@ -124,7 +123,8 @@ function pluginPWA(context, options) {
                 },
                 plugins: [
                     new webpack_1.default.EnvironmentPlugin({
-                        PWA_SW_CUSTOM: swCustom || '', // fallback value required with Webpack 5
+                        // Fallback value required with Webpack 5
+                        PWA_SW_CUSTOM: swCustom || '',
                     }),
                     new LogPlugin_1.default({
                         name: 'Service Worker',
@@ -149,11 +149,10 @@ function pluginPWA(context, options) {
                     '**/*.{js,json,css,html}',
                     '**/*.{png,jpg,jpeg,gif,svg,ico}',
                     '**/*.{woff,woff2,eot,ttf,otf}',
-                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                    // @ts-ignore
-                    ...(workbox_build_1.injectManifest.globPatterns || []),
+                    // @ts-expect-error: internal API?
+                    ...(workbox_build_1.injectManifest.globPatterns ?? []),
                 ],
-                // those attributes are not overrideable
+                // Those attributes are not overrideable
                 swDest,
                 swSrc: swDest,
                 globDirectory: props.outDir,

package/lib/options.d.ts

@@ -4,8 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Joi } from '@docusaurus/utils-validation';
-import type { ThemeConfig, ValidationResult, OptionValidationContext } from '@docusaurus/types';
+import type { OptionValidationContext } from '@docusaurus/types';
 import type { PluginOptions } from '@docusaurus/plugin-pwa';
-export declare const Schema: Joi.ObjectSchema<any>;
-export declare function validateOptions({ validate, options, }: OptionValidationContext<PluginOptions>): ValidationResult<ThemeConfig>;
+export declare function validateOptions({ validate, options, }: OptionValidationContext<PluginOptions, PluginOptions>): PluginOptions;

package/lib/options.js

@@ -6,9 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateOptions = exports.Schema = void 0;
-const tslib_1 = require("tslib");
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
+exports.validateOptions = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const DEFAULT_OPTIONS = {
     debug: false,
@@ -20,10 +18,10 @@ const DEFAULT_OPTIONS = {
     injectManifestConfig: {},
     pwaHead: [],
     swCustom: undefined,
-    swRegister: path_1.default.join(__dirname, 'registerSw.js'),
+    swRegister: './registerSw.js',
     reloadPopup: '@theme/PwaReloadPopup',
 };
-exports.Schema = utils_validation_1.Joi.object({
+const Schema = utils_validation_1.Joi.object({
     debug: utils_validation_1.Joi.bool().default(DEFAULT_OPTIONS.debug),
     offlineModeActivationStrategies: utils_validation_1.Joi.array()
         .items(utils_validation_1.Joi.string()
@@ -43,6 +41,6 @@ exports.Schema = utils_validation_1.Joi.object({
         .default(DEFAULT_OPTIONS.reloadPopup),
 });
 function validateOptions({ validate, options, }) {
-    return validate(exports.Schema, options);
+    return validate(Schema, options);
 }
 exports.validateOptions = validateOptions;

package/lib/registerSw.js

@@ -16,7 +16,7 @@ const PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES =
 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;
 
@@ -79,7 +79,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();
@@ -101,7 +101,7 @@ async function getActiveStrategies() {
       return isActive ? strategyName : undefined;
     }),
   );
-  return activeStrategies.filter(Boolean); // remove undefined values
+  return activeStrategies.filter(Boolean);
 }
 
 async function isOfflineModeEnabled() {

package/lib/sw.js

@@ -18,7 +18,7 @@ function parseSwParams() {
   return params;
 }
 
-// doc advises 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 looks it's working fine as it's inlined by webpack, need to double check
@@ -73,7 +73,8 @@ function getPossibleURLs(url) {
   // eslint-disable-next-line no-underscore-dangle
   const precacheManifest = self.__WB_MANIFEST;
   const controller = new PrecacheController({
-    fallbackToNetwork: true, // safer to turn this true?
+    // Safer to turn this true?
+    fallbackToNetwork: true,
   });
 
   if (params.offlineMode) {
@@ -137,7 +138,7 @@ function getPossibleURLs(url) {
       });
     }
 
-    const type = event.data && event.data.type;
+    const type = event.data?.type;
 
     if (type === 'SKIP_WAITING') {
       self.skipWaiting();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-pwa",
-  "version": "2.0.0-beta.16",
+  "version": "2.0.0-beta.19",
   "description": "Docusaurus Plugin to add PWA support.",
   "main": "lib/index.js",
   "types": "src/plugin-pwa.d.ts",
@@ -20,31 +20,31 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@babel/core": "^7.17.5",
-    "@babel/preset-env": "^7.16.11",
-    "@docusaurus/core": "2.0.0-beta.16",
-    "@docusaurus/theme-common": "2.0.0-beta.16",
-    "@docusaurus/theme-translations": "2.0.0-beta.16",
-    "@docusaurus/utils": "2.0.0-beta.16",
-    "@docusaurus/utils-validation": "2.0.0-beta.16",
-    "babel-loader": "^8.2.3",
+    "@babel/core": "^7.17.10",
+    "@babel/preset-env": "^7.17.10",
+    "@docusaurus/core": "2.0.0-beta.19",
+    "@docusaurus/theme-common": "2.0.0-beta.19",
+    "@docusaurus/theme-translations": "2.0.0-beta.19",
+    "@docusaurus/utils": "2.0.0-beta.19",
+    "@docusaurus/utils-validation": "2.0.0-beta.19",
+    "babel-loader": "^8.2.5",
     "clsx": "^1.1.1",
-    "core-js": "^3.21.0",
+    "core-js": "^3.22.3",
     "terser-webpack-plugin": "^5.3.1",
-    "tslib": "^2.3.1",
-    "webpack": "^5.69.1",
+    "tslib": "^2.4.0",
+    "webpack": "^5.72.0",
     "webpack-merge": "^5.8.0",
-    "workbox-build": "^6.5.0",
-    "workbox-precaching": "^6.5.0",
-    "workbox-window": "^6.5.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.16",
-    "fs-extra": "^10.0.1"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.19",
+    "fs-extra": "^10.1.0"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
-  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
+  "gitHead": "a71e60a49cce93c1006ef10c41ac03187f057102"
 }

package/src/index.ts

@@ -64,14 +64,14 @@ export default function pluginPWA(
     name: 'docusaurus-plugin-pwa',
 
     getThemePath() {
-      return path.resolve(__dirname, '../lib/theme');
+      return '../lib/theme';
     },
     getTypeScriptThemePath() {
-      return path.resolve(__dirname, '../src/theme');
+      return '../src/theme';
     },
 
     getClientModules() {
-      return isProd ? [swRegister] : [];
+      return isProd && swRegister ? [swRegister] : [];
     },
 
     getDefaultCodeTranslationMessages() {
@@ -138,7 +138,7 @@ export default function pluginPWA(
       const swSourceFileTest = /\.m?js$/;
 
       const swWebpackConfig: Configuration = {
-        entry: path.resolve(__dirname, 'sw.js'),
+        entry: require.resolve('./sw.js'),
         output: {
           path: outDir,
           filename: 'sw.js',
@@ -150,7 +150,7 @@ export default function pluginPWA(
         optimization: {
           splitChunks: false,
           minimize: !debug,
-          // see https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack
+          // See https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack
           minimizer: debug
             ? []
             : [
@@ -161,7 +161,8 @@ export default function pluginPWA(
         },
         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',
@@ -189,11 +190,10 @@ export default function pluginPWA(
           '**/*.{js,json,css,html}',
           '**/*.{png,jpg,jpeg,gif,svg,ico}',
           '**/*.{woff,woff2,eot,ttf,otf}',
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-ignore
-          ...(injectManifest.globPatterns || []),
+          // @ts-expect-error: internal API?
+          ...(injectManifest.globPatterns ?? []),
         ],
-        // those attributes are not overrideable
+        // Those attributes are not overrideable
         swDest,
         swSrc: swDest,
         globDirectory: props.outDir,

package/src/options.ts

@@ -5,13 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import path from 'path';
 import {Joi} from '@docusaurus/utils-validation';
-import type {
-  ThemeConfig,
-  ValidationResult,
-  OptionValidationContext,
-} from '@docusaurus/types';
+import type {OptionValidationContext} from '@docusaurus/types';
 import type {PluginOptions} from '@docusaurus/plugin-pwa';
 
 const DEFAULT_OPTIONS = {
@@ -24,11 +19,11 @@ const DEFAULT_OPTIONS = {
   injectManifestConfig: {},
   pwaHead: [],
   swCustom: undefined,
-  swRegister: path.join(__dirname, 'registerSw.js'),
+  swRegister: './registerSw.js',
   reloadPopup: '@theme/PwaReloadPopup',
 };
 
-export const Schema = Joi.object({
+const Schema = Joi.object({
   debug: Joi.bool().default(DEFAULT_OPTIONS.debug),
   offlineModeActivationStrategies: Joi.array()
     .items(
@@ -62,6 +57,6 @@ export const Schema = Joi.object({
 export function validateOptions({
   validate,
   options,
-}: OptionValidationContext<PluginOptions>): ValidationResult<ThemeConfig> {
+}: OptionValidationContext<PluginOptions, PluginOptions>): PluginOptions {
   return validate(Schema, options);
 }

package/src/plugin-pwa.d.ts

@@ -6,26 +6,92 @@
  */
 
 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 | 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

@@ -16,7 +16,7 @@ const PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES =
 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;
 
@@ -79,7 +79,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();
@@ -101,7 +101,7 @@ async function getActiveStrategies() {
       return isActive ? strategyName : undefined;
     }),
   );
-  return activeStrategies.filter(Boolean); // remove undefined values
+  return activeStrategies.filter(Boolean);
 }
 
 async function isOfflineModeEnabled() {

package/src/sw.js

@@ -18,7 +18,7 @@ function parseSwParams() {
   return params;
 }
 
-// doc advises 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 looks it's working fine as it's inlined by webpack, need to double check
@@ -73,7 +73,8 @@ function getPossibleURLs(url) {
   // eslint-disable-next-line no-underscore-dangle
   const precacheManifest = self.__WB_MANIFEST;
   const controller = new PrecacheController({
-    fallbackToNetwork: true, // safer to turn this true?
+    // Safer to turn this true?
+    fallbackToNetwork: true,
   });
 
   if (params.offlineMode) {
@@ -137,7 +138,7 @@ function getPossibleURLs(url) {
       });
     }
 
-    const type = event.data && event.data.type;
+    const type = event.data?.type;
 
     if (type === 'SKIP_WAITING') {
       self.skipWaiting();