バージョン: 3.5.2

📦 plugin-pwa

Workboxを使用してPWAサポートを追加するDocusaurusプラグイン。このプラグインは、本番ビルドのみにService Workerを生成し、オフラインおよびインストールサポートを備えた完全なPWA準拠のドキュメントサイトを作成できます。

インストール

npm
Yarn
pnpm

npm install --save @docusaurus/plugin-pwa

yarn add @docusaurus/plugin-pwa

pnpm add @docusaurus/plugin-pwa

設定

./static/manifest.jsonにPWAマニフェストを作成します。

以下のような最小限のPWA設定でdocusaurus.config.jsを変更します。

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        debug: true,
        offlineModeActivationStrategies: [
          'appInstalled',
          'standalone',
          'queryString',
        ],
        pwaHead: [
          {
            tagName: 'link',
            rel: 'icon',
            href: '/img/docusaurus.png',
          },
          {
            tagName: 'link',
            rel: 'manifest',
            href: '/manifest.json', // your PWA manifest
          },
          {
            tagName: 'meta',
            name: 'theme-color',
            content: 'rgb(37, 194, 160)',
          },
        ],
      },
    ],
  ],
};

プログレッシブウェブアプリ

Service Workerがインストールされているだけでは、アプリケーションをPWAにするには不十分です。少なくともWebアプリマニフェストを含め、<head>に正しいタグを付ける必要があります（オプション > pwaHead）。

デプロイ後、Lighthouseを使用してサイトの監査を実行できます。

サイトをPWAにするために必要な事項のより網羅的なリストについては、PWAチェックリストを参照してください。

アプリのインストールサポート

ブラウザがサポートしている場合、Docusaurusサイトをアプリとしてインストールできるはずです。

A screen recording of the installation process. A button appears in the address bar of the browser, which displays a dialog asking "install this application?" when clicked. After clicking the "Install" button, a new application is opened in the operating system, opening to the Docusaurus homepage.

注記

アプリのインストールには、HTTPSプロトコルと有効なマニフェストが必要です。

オフラインモード（プリキャッシング）

Service Workerのプリキャッシングを使用して、ユーザーがDocusaurusサイトをオフラインで閲覧できるようにします。

workbox-precachingページでは、このアイデアについて説明しています。

Service Workerの機能の1つは、Service Workerのインストール時に一連のファイルをキャッシュに保存できることです。これは、Service Workerが使用される前にコンテンツをキャッシュするため、「プリキャッシング」と呼ばれることがよくあります。

これを行う主な理由は、開発者がキャッシュを制御できるようになることです。つまり、ファイルがキャッシュされるタイミングと期間を決定できるだけでなく、ネットワークにアクセスせずにブラウザに提供できるため、オフラインで動作するWebアプリを作成するために使用できます。

Workboxは、APIを簡素化し、アセットが効率的にダウンロードされるようにすることで、プリキャッシングの手間を大幅に軽減します。

デフォルトでは、サイトがアプリとしてインストールされている場合、オフラインモードが有効になります。詳細は、offlineModeActivationStrategiesオプションを参照してください。

サイトがプリキャッシュされた後、Service Workerは、その後の訪問に対してキャッシュされたレスポンスを提供します。新しいビルドが新しいService Workerと共にデプロイされると、新しいService Workerのインストールが開始され、最終的に待機状態に移行します。この待機状態の間、リロードポップアップが表示され、ユーザーに新しいコンテンツのためにページをリロードするように求めます.ユーザーがアプリケーションキャッシュをクリアするか、ポップアップの `reload` ボタンをクリックするまで、Service Workerは古いコンテンツの提供を続けます。

警告

オフラインモード/プリキャッシングでは、サイトのすべての静的アセットを事前にダウンロードする必要があるため、不要な帯域幅を消費する可能性があります。すべての種類のサイトでアクティブにするのは良い考えではないかもしれません。

オプション

`debug`

タイプ: boolean
デフォルト: false

デバッグモードをオンにする

Workboxログ
追加のDocusaurusログ
最適化されていないSWファイル出力
ソースマップ

`offlineModeActivationStrategies`

タイプ: ('appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always')[]
デフォルト: ['appInstalled', 'queryString', 'standalone']

オフラインモードをオンにするために使用される戦略

appInstalled: サイトをアプリとしてインストールしたユーザーに対してアクティブになります（100％信頼できるわけではありません）
standalone: アプリをスタンドアロンとして実行しているユーザーに対してアクティブになります（多くの場合、PWAがインストールされるとそうなります）
queryString: クエリ文字列にofflineMode=trueが含まれている場合にアクティブになります（PWAのデバッグに便利）
mobile: モバイルユーザー（width <= 996px）に対してアクティブになります
saveData: navigator.connection.saveData === trueのユーザーに対してアクティブになります
always: すべてのユーザーに対してアクティブになります

警告

注意して使用してください。オフラインモードの使用を強制されることを好まないユーザーもいるかもしれません。

危険

ページがPWAとしてレンダリングされているかどうかを確実に検出することはできません。

appinstalledイベントは仕様から削除され、navigator.getInstalledRelatedApps() APIは最近のChromeバージョンでのみサポートされており、マニフェストでrelated_applicationsが宣言されている必要があります。

standalone戦略は、オフラインモードをアクティブにするための優れたフォールバックです（少なくともインストールされたアプリを実行している場合）。

`injectManifestConfig`

workbox.injectManifest()に渡すWorkboxオプション。これにより、どのアセットがプリキャッシュされ、オフラインで利用できるかを制御できます。

タイプ: InjectManifestOptions
デフォルト: {}

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        injectManifestConfig: {
          manifestTransforms: [
            //...
          ],
          modifyURLPrefix: {
            //...
          },
          // We already add regular static assets (HTML, images...) to be available offline
          // You can add more files according to your needs
          globPatterns: ['**/*.{pdf,docx,xlsx}'],
          // ...
        },
      },
    ],
  ],
};

`pwaHead`

タイプ: ({ tagName: string; [attributeName: string]: string })[]
デフォルト: []

tagNameと、<head>タグに挿入する属性のキーと値のペアを含むオブジェクトの配列。技術的には、これを通じて任意のヘッドタグを挿入できますが、サイトをPWA準拠にするためのタグに理想的に使用されます。アプリを完全に準拠させるためのタグのリストを以下に示します。

export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        pwaHead: [
          {
            tagName: 'link',
            rel: 'icon',
            href: '/img/docusaurus.png',
          },
          {
            tagName: 'link',
            rel: 'manifest',
            href: '/manifest.json',
          },
          {
            tagName: 'meta',
            name: 'theme-color',
            content: 'rgb(37, 194, 160)',
          },
          {
            tagName: 'meta',
            name: 'apple-mobile-web-app-capable',
            content: 'yes',
          },
          {
            tagName: 'meta',
            name: 'apple-mobile-web-app-status-bar-style',
            content: '#000',
          },
          {
            tagName: 'link',
            rel: 'apple-touch-icon',
            href: '/img/docusaurus.png',
          },
          {
            tagName: 'link',
            rel: 'mask-icon',
            href: '/img/docusaurus.svg',
            color: 'rgb(37, 194, 160)',
          },
          {
            tagName: 'meta',
            name: 'msapplication-TileImage',
            content: '/img/docusaurus.png',
          },
          {
            tagName: 'meta',
            name: 'msapplication-TileColor',
            content: '#000',
          },
        ],
      },
    ],
  ],
};

`swCustom`

タイプ: `string | undefined`
デフォルト: `undefined`

追加のWorkboxルールに役立ちます。Service Workerができることは何でもここで行うことができ、workboxライブラリのフルパワーを使用できます。コードはトランスパイルされるため、最新のES6以降の構文をここで使用できます。

たとえば、外部ルートからファイルをキャッシュするには、

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';

// default fn export receiving some useful params
export default function swCustom(params) {
  const {
    debug, // :boolean
    offlineMode, // :boolean
  } = params;

  // Cache responses from external resources
  registerRoute((context) => {
    return [
      /graph\.facebook\.com\/.*\/picture/,
      /netlify\.com\/img/,
      /avatars1\.githubusercontent/,
    ].some((regex) => context.url.href.match(regex));
  }, new StaleWhileRevalidate());
}

モジュールは`default`関数エクスポートを持ち、いくつかのパラメータを受け取る必要があります。

`swRegister`

種類: string | false
デフォルト: 'docusaurus-plugin-pwa/src/registerSW.js'

Docusaurusアプリが実行される前に登録が行われるように、Docusaurusアプリの前にエントリを追加します。デフォルトのregisterSW.jsファイルは、単純な登録には十分です。

falseを渡すと、登録は完全に無効になります。

マニフェストの例

Docusaurusサイトのマニフェストは参考になります。

{
  "name": "Docusaurus",
  "short_name": "Docusaurus",
  "theme_color": "#2196f3",
  "background_color": "#424242",
  "display": "standalone",
  "scope": "./",
  "start_url": "./index.html",
  "related_applications": [
    {
      "platform": "webapp",
      "url": "https://docusaurus.dokyumento.jp/manifest.json"
    }
  ],
  "icons": [
    {
      "src": "img/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

新しいサービスワーカーのインストールを待機している場合、@theme/PwaReloadPopupコンポーネントが表示され、ユーザーにリロードを提案します。このコンポーネントをswizzleして、独自のUIを実装できます。それは、小道具としてonReloadコールバックを受け取ります。これは、reloadボタンがクリックされたときに呼び出されるべきです。これは、サービスワーカーに待機中のサービスワーカーをインストールしてページをリロードするように指示します。

デフォルトのテーマには、リロードポップアップの実装が含まれており、Infima Alertsを使用しています。

A screen recording of the reload process. An alert box shows in the bottom right of the window, saying "New content available". After clicking the "Refresh" button, the page's main heading changes from "Introduction" to "PWA :))".

コンポーネントはnullをレンダリングできますが、これは推奨されません。ユーザーは最新のコンテンツを取得する方法がありません。

インストール​

設定​

プログレッシブウェブアプリ​

アプリのインストールサポート​

オフラインモード（プリキャッシング）​

オプション​

debug​

offlineModeActivationStrategies​

injectManifestConfig​

pwaHead​

swCustom​

swRegister​

マニフェストの例​

リロードポップアップのカスタマイズ​