@azerion/bunosaurus-plugin-pwa 0.0.0-stage → 4.0.0

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@azerion/bunosaurus-plugin-pwa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "Docusaurus Plugin to add PWA support.",
+  "main": "lib/index.js",
+  "types": "src/plugin-pwa.d.ts",
+  "scripts": {
+    "build": "tsc --build && copy-untyped-files && oxfmt \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "copy-untyped-files --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-plugin-pwa"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/bundler": "npm:@azerion/bunosaurus-bundler@4.0.0",
+    "@docusaurus/core": "npm:@azerion/bunosaurus-core@4.0.0",
+    "@docusaurus/logger": "npm:@azerion/bunosaurus-logger@4.0.0",
+    "@docusaurus/theme-common": "npm:@azerion/bunosaurus-theme-common@4.0.0",
+    "@docusaurus/theme-translations": "npm:@azerion/bunosaurus-theme-translations@4.0.0",
+    "@docusaurus/types": "npm:@azerion/bunosaurus-types@4.0.0",
+    "@docusaurus/utils": "npm:@azerion/bunosaurus-utils@4.0.0",
+    "@docusaurus/utils-validation": "npm:@azerion/bunosaurus-utils-validation@4.0.0",
+    "clsx": "^2.1.1",
+    "tslib": "^2.8.1",
+    "workbox-build": "^7.4.1",
+    "workbox-precaching": "^7.4.1",
+    "workbox-window": "^7.4.1"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "npm:@azerion/bunosaurus-module-type-aliases@4.0.0",
+    "@types/react-dom": "^19.3.0"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 path from 'node:path';
+import {bunBuild} from '@docusaurus/bundler';
+import {injectManifest} from 'workbox-build';
+import {normalizeUrl} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import type {HtmlTags, LoadContext, Plugin} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-pwa';
+
+const PluginName = 'docusaurus-plugin-pwa';
+
+export default function pluginPWA(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin<void> | null {
+  if (process.env.NODE_ENV !== 'production') {
+    return null;
+  }
+  if (context.siteConfig.future.experimental_router === 'hash') {
+    logger.warn(
+      `${PluginName} does not support the Hash Router and will be disabled.`,
+    );
+    return null;
+  }
+
+  const {
+    outDir,
+    baseUrl,
+    i18n: {currentLocale},
+  } = context;
+  const {
+    debug,
+    offlineModeActivationStrategies,
+    injectManifestConfig,
+    pwaHead,
+    swCustom,
+    swRegister,
+  } = options;
+
+  return {
+    name: PluginName,
+
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+
+    getClientModules() {
+      return swRegister ? [swRegister] : [];
+    },
+
+    getDefaultCodeTranslationMessages() {
+      return readDefaultCodeTranslationMessages({
+        locale: currentLocale,
+        name: 'plugin-pwa',
+      });
+    },
+
+    configureWebpack(config, isServer, {currentBundler}) {
+      return {
+        plugins: [
+          new currentBundler.instance.EnvironmentPlugin({
+            PWA_DEBUG: debug,
+            PWA_SERVICE_WORKER_URL: path.posix.resolve(
+              `${(config.output?.publicPath as string) || '/'}`,
+              'sw.js',
+            ),
+            PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES:
+              offlineModeActivationStrategies,
+          }),
+        ],
+      };
+    },
+
+    injectHtmlTags() {
+      const headTags: HtmlTags = [];
+      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};
+    },
+
+    async postBuild(props) {
+      // The service worker is a classic script, bundled on its own
+      await bunBuild('Service Worker', {
+        entrypoints: [require.resolve('./sw.js')],
+        outdir: outDir,
+        naming: 'sw.js',
+        target: 'browser',
+        format: 'iife',
+        minify: !debug,
+        sourcemap: debug ? 'linked' : 'none',
+        publicPath: baseUrl,
+        env: 'disable',
+        define: {
+          'process.env.NODE_ENV': JSON.stringify(
+            debug ? 'development' : 'production',
+          ),
+          'process.env.PWA_SW_CUSTOM': JSON.stringify(swCustom ?? ''),
+        },
+      });
+
+      const swDest = path.resolve(props.outDir, 'sw.js');
+
+      await injectManifest({
+        ...injectManifestConfig,
+        globPatterns: [
+          '**/*.{js,json,css,html}',
+          '**/*.{png,jpg,jpeg,gif,svg,ico}',
+          '**/*.{woff,woff2,eot,ttf,otf}',
+          // @ts-expect-error: internal API?
+          ...((injectManifest.globPatterns as string[] | undefined) ?? []),
+        ],
+        // Those attributes are not overrideable
+        swDest,
+        swSrc: swDest,
+        globDirectory: props.outDir,
+      });
+    },
+  };
+}
+
+export {validateOptions} from './options';

package/src/options.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 {Joi} from '@docusaurus/utils-validation';
+import type {OptionValidationContext} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-pwa';
+
+const DEFAULT_OPTIONS = {
+  debug: false,
+  offlineModeActivationStrategies: [
+    'appInstalled',
+    'queryString',
+    'standalone',
+  ],
+  injectManifestConfig: {},
+  pwaHead: [],
+  swCustom: undefined,
+  swRegister: './registerSw.js',
+};
+
+const optionsSchema = Joi.object<PluginOptions>({
+  debug: Joi.bool().default(DEFAULT_OPTIONS.debug),
+  offlineModeActivationStrategies: Joi.array()
+    .items(
+      Joi.string()
+        .valid(
+          'appInstalled',
+          'queryString',
+          'standalone',
+          'mobile',
+          'saveData',
+          'always',
+        )
+        .required(),
+    )
+    .default(DEFAULT_OPTIONS.offlineModeActivationStrategies),
+  injectManifestConfig: Joi.object().default(
+    DEFAULT_OPTIONS.injectManifestConfig,
+  ),
+  pwaHead: Joi.array()
+    .items(Joi.object({tagName: Joi.string().required()}).unknown().required())
+    .default(DEFAULT_OPTIONS.pwaHead),
+  swCustom: Joi.string(),
+  swRegister: Joi.alternatives()
+    .try(Joi.string(), Joi.bool().valid(false))
+    .default(DEFAULT_OPTIONS.swRegister),
+  // @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,90 @@
+/**
+ * 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' {
+  import type {ReactNode} from 'react';
+
+  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): ReactNode;
+}

package/src/registerSw.ts

@@ -0,0 +1,242 @@
+/**
+ * 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 ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {createStorageSlot} from '@docusaurus/theme-common';
+
+// First: read the env variables (provided by Webpack)
+
+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;
+
+const MAX_MOBILE_WIDTH = 996;
+
+const AppInstalledEventFiredStorage = createStorageSlot(
+  'docusaurus.pwa.event.appInstalled.fired',
+);
+
+declare global {
+  interface Navigator {
+    getInstalledRelatedApps: () => Promise<{platform: string}[]>;
+    connection?: {effectiveType: string; saveData: boolean};
+  }
+}
+
+function debugLog(msg: string, obj?: unknown) {
+  if (PWA_DEBUG) {
+    if (typeof obj === 'undefined') {
+      console.log(`[Docusaurus-PWA][registerSw]: ${msg}`);
+    } else {
+      console.log(`[Docusaurus-PWA][registerSw]: ${msg}`, obj);
+    }
+  }
+}
+
+async function clearRegistrations() {
+  const registrations = await navigator.serviceWorker.getRegistrations();
+  debugLog('will unregister all service workers', {registrations});
+  await Promise.all(
+    registrations.map((registration) =>
+      registration
+        .unregister()
+        .then((result) =>
+          debugLog('unregister service worker', {registration, result}),
+        ),
+    ),
+  );
+  debugLog('unregistered all service workers', {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/
+ */
+function getIsAppInstalledEventFired() {
+  return AppInstalledEventFiredStorage.get() === 'true';
+}
+
+async function getIsAppInstalledRelatedApps() {
+  if (!('getInstalledRelatedApps' in window.navigator)) {
+    return false;
+  }
+  try {
+    const relatedApps = await navigator.getInstalledRelatedApps();
+    return relatedApps.some((app) => app.platform === 'webapp');
+  } catch {
+    // Error might be thrown when Docusaurus is embedded in an iframe:
+    // registerSW failed DOMException: Failed to execute 'getInstalledRelatedApps' on 'Navigator': getInstalledRelatedApps() is only supported in top-level browsing contexts.
+    return false;
+  }
+}
+function isStandaloneDisplayMode() {
+  return window.matchMedia('(display-mode: standalone)').matches;
+}
+
+const OfflineModeActivationStrategiesImplementations = {
+  always: () => true,
+  mobile: () => window.innerWidth <= MAX_MOBILE_WIDTH,
+  saveData: () => !!navigator.connection?.saveData,
+  appInstalled: () =>
+    getIsAppInstalledEventFired() || getIsAppInstalledRelatedApps(),
+  standalone: () => isStandaloneDisplayMode(),
+  queryString: () =>
+    new URLSearchParams(window.location.search).get('offlineMode') === 'true',
+};
+
+async function getActiveStrategies() {
+  const activeStrategies = await Promise.all(
+    PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES.map((strategyName) =>
+      Promise.resolve(
+        OfflineModeActivationStrategiesImplementations[strategyName](),
+      ).then((isActive) => (isActive ? strategyName : undefined)),
+    ),
+  );
+  return activeStrategies.filter(Boolean);
+}
+
+async function getIsOfflineModeEnabled() {
+  const activeStrategies = await getActiveStrategies();
+  const enabled = activeStrategies.length > 0;
+  debugLog(
+    enabled
+      ? 'offline mode enabled, because of activation strategies'
+      : 'offline mode disabled, because none of the offlineModeActivationStrategies could be used',
+    {
+      activeStrategies,
+      availableStrategies: PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES,
+    },
+  );
+  return enabled;
+}
+
+function createServiceWorkerUrl(params: object) {
+  const paramsQueryString = JSON.stringify(params);
+  const url = `${PWA_SERVICE_WORKER_URL}?params=${encodeURIComponent(
+    paramsQueryString,
+  )}`;
+  debugLog('service worker url', {url, params});
+  return url;
+}
+
+async function registerSW() {
+  const [{Workbox}, offlineMode] = await Promise.all([
+    import('workbox-window'),
+    getIsOfflineModeEnabled(),
+  ]);
+  const url = createServiceWorkerUrl({offlineMode, debug: PWA_DEBUG});
+  const wb = new Workbox(url);
+  const sendSkipWaiting = () => wb.messageSW({type: 'SKIP_WAITING'});
+  const handleServiceWorkerWaiting = () => {
+    debugLog('handleServiceWorkerWaiting');
+    // Immediately load new service worker when files aren't cached
+    if (!offlineMode) {
+      return sendSkipWaiting();
+    }
+    return import('./renderReloadPopup.js').then(({renderReloadPopup}) =>
+      renderReloadPopup({
+        onReload() {
+          wb.addEventListener('controlling', () => {
+            window.location.reload();
+          });
+          sendSkipWaiting();
+        },
+      }),
+    );
+  };
+  // Update the current service worker when the next one has finished
+  // installing and transitions to waiting state.
+  wb.addEventListener('waiting', (event) => {
+    debugLog('event waiting', {event});
+    void handleServiceWorkerWaiting();
+  });
+  // 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) => {
+    debugLog('event externalwaiting', {event});
+    void handleServiceWorkerWaiting();
+  });
+  const registration = await wb.register();
+  if (registration) {
+    if (registration.active) {
+      debugLog('registration.active', {registration});
+    }
+    if (registration.installing) {
+      debugLog('registration.installing', {registration});
+    }
+    if (registration.waiting) {
+      debugLog('registration.waiting', {registration});
+      // 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.
+      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() {
+  debugLog('addLegacyAppInstalledEventsListeners');
+
+  window.addEventListener('appinstalled', (event) => {
+    debugLog('event appinstalled', {event});
+    AppInstalledEventFiredStorage.set('true');
+    debugLog("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.
+    void clearRegistrations();
+  });
+
+  // TODO this event still works in chrome but has been removed from the spec
+  // in 2019!!!
+  window.addEventListener('beforeinstallprompt', (event) => {
+    debugLog('event beforeinstallprompt', {event});
+    // TODO instead of default browser install UI, show custom docusaurus
+    // prompt?
+    // event.preventDefault();
+    const appInstalledEventFired = AppInstalledEventFiredStorage.get();
+    debugLog('AppInstalledEventFiredStorage.get()', {appInstalledEventFired});
+    if (appInstalledEventFired) {
+      AppInstalledEventFiredStorage.del();
+      debugLog('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 shows.
+      void clearRegistrations();
+    }
+  });
+
+  debugLog(
+    'legacy appinstalled and beforeinstallprompt event listeners installed',
+  );
+}
+
+/*
+Init code to run on the client!
+ */
+if (ExecutionEnvironment.canUseDOM) {
+  debugLog('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: unknown) => console.error('registerSW failed', e));
+  }
+}

package/src/renderReloadPopup.tsx

@@ -0,0 +1,28 @@
+/**
+ * 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 {createRoot} from 'react-dom/client';
+import type {Props} from '@theme/PwaReloadPopup';
+
+const POPUP_CONTAINER_ID = 'pwa-popup-container';
+
+const getContainer = () => document.getElementById(POPUP_CONTAINER_ID);
+
+const createContainer = () => {
+  const container = document.createElement('div');
+  container.id = POPUP_CONTAINER_ID;
+  document.body.appendChild(container);
+  return container;
+};
+
+export function renderReloadPopup(props: Props): Promise<void> {
+  const container = getContainer() ?? createContainer();
+  return import('@theme/PwaReloadPopup').then(({default: ReloadPopup}) => {
+    const root = createRoot(container);
+    root.render(<ReloadPopup {...props} />);
+  });
+}