pluginPwa

SSGの成果物にWeb App ManifestとService Workerを追加するプラグイン。

導入と自動再読み込みの例はPWA対応ガイドを参照してください。

Table of Contents

依存関係と戻り値

vite-plugin-pwaはoptional peer dependencyです。npm install -D vite-plugin-pwaで追加してください。未インストールでもministaの他の機能は利用でき、pluginPwa()を呼び出した場合にのみMINISTA_PWA_DEPENDENCY_MISSINGを報告します。

戻り値はPromise<Plugin[]>です。defineConfig()のpluginsへそのまま追加できます。

オプション

以下のオプションをvite-plugin-pwaへ渡します。

オプション型既定値説明
registerType"prompt" | "autoUpdate""prompt"更新の適用方法。自動再読み込みにはクライアントの登録コードも必要です。
injectRegister"auto" | "inline" | "script" | "script-defer" | false | null"auto"Service Worker登録コードの挿入方法。"auto"ではvirtual moduleの使用を検出し、使用時は別の登録スクリプトを挿入しません。
manifestfalse | { [key: string]: unknown }vite-plugin-pwaの既定値Web App Manifestの設定。falseでManifest生成を無効にします。
manifestFilenamestring"manifest.webmanifest"Manifestの出力ファイル名。
filenamestring"sw.js"Service Workerの出力ファイル名。
basestringViteのbasePWAファイルの公開URLの基準。
scopestringbaseのパスService Workerが制御するURLの範囲。
disablebooleanfalsePWAの生成とHTMLへのタグ挿入を無効にします。
workbox{ [key: string]: unknown }下記参照generateSWに渡す設定。
includeAssetsstring | string[]undefinedpublic内で追加保存するファイルをglobで指定します。
useCredentialsbooleanfalseManifestのlinkにcrossorigin="use-credentials"を付けます。

manifestはサイト名・開始URL・表示モードなどの上流の既定値とマージされます。アイコンはプロジェクト側で用意してください。ManifestのフィールドはWeb App Manifest、登録方法はvite-plugin-pwaの登録ガイドを参照してください。

workboxの既定値

pluginPwa({
  workbox: {
    globPatterns: [
      "**/*.{html,js,css,json,svg,png,jpg,jpeg,webp,avif,ico,woff,woff2}",
    ],
    navigateFallback: null,
  },
})

上記はministaが設定する既定値です。その他はvite-plugin-pwaとWorkboxの設定に従います。workboxで個別に上書きできます。globPatternsの配列は置き換えになり、追加する場合も必要な拡張子をすべて指定します。

複数の静的HTMLを持つサイト向けに、navigateFallbackをnullにしています。存在しないページをトップページへ置き換えるSPA用fallbackを既定では使いません。キャッシュ対象にはWorkboxのサイズ上限や除外設定も適用されます。詳細はprecacheとgenerateSWを参照してください。

対応範囲と診断

Service WorkerはgenerateSW方式で生成します。strategies・injectManifest・devOptionsなど、PluginPwaOptionsにない上流オプションは公開APIの対応範囲に含みません。

Manifestのlinkと登録用scriptをSSGの各HTMLのheadに挿入します。既存のManifestのlinkがある場合は重複追加しません。virtual:pwa-registerを使う場合は、各ページで共通のクライアントエントリーを読み込んでください。

診断コード条件と対処
MINISTA_PWA_DEPENDENCY_MISSINGvite-plugin-pwaがありません。optional peerをインストールします。
MINISTA_PWA_HEAD_MISSINGPWAタグの挿入先にheadがありません。レイアウトへheadを追加します。