PWA マニフェストとサービスワーカー#

Copy as MarkdownView Markdown

pwa を有効にし、ssg.siteUrl があると、SSG ビルドは生成 HTML の横に Web アプリマニフェストを書き、既定では保守的なサービスワーカーも書きます。

• manifest.webmanifest — 名前、開始 URL、テーマ色、standalone 表示
• sw.js — ハッシュ付き assets/ と HTML ページをキャッシュ

テーマ付きページには <link rel="manifest"> も付きます。オフラインキャッシュが オンのときは、sw.js を登録する小さなスクリプトも入ります。

これはクライアント JavaScript を追加します。 登録スクリプトはブラウザで 動きます。サービスワーカーは同一オリジンの GET を横取りします。機能を オンにするまで既存サイトは変わりません。

import { oxContent } from "@ox-content/vite-plugin";

export default {
  plugins: [
    oxContent({
      pwa: true,
      ssg: {
        siteUrl: "https://example.com",
      },
    }),
  ],
};

false または省略ではファイルもクライアントスクリプトもオフです。true は 既定を有効にします。マニフェストとオフラインキャッシュです。オブジェクトは 機能をオンにしたうえで、指定したフィールドだけ上書きします。

oxContent({
  pwa: {
    name: "Docs",
    shortName: "Docs",
    themeColor: "#0f172a",
    backgroundColor: "#ffffff",
    startUrl: "/docs/",
  },
  ssg: {
    siteUrl: "https://example.com",
    siteName: "Docs",
  },
});

マニフェストのみ（オフラインキャッシュなし）#

offline: false にすると、インストール用メタデータは残し、サービスワーカー と登録スクリプトは出しません。manifest.webmanifest と <link rel="manifest"> は書きます。sw.js は書きません。

oxContent({
  pwa: {
    offline: false,
    name: "Docs",
  },
  ssg: {
    siteUrl: "https://example.com",
  },
});

start_url と scope はオリジン付き絶対 URL ではなく、サイト相対パスです。 javascript:、プロトコル相対の //、パス以外の値は base に戻します。 テーマ色と背景色は #rgb / #rrggbb / #rrggbbaa または CSS 色名です。 不正な値は既定に戻します。

オフラインキャッシュの挙動#

サービスワーカーは保守的です。

• HTML ページ は network-first です。キャッシュはネットワーク失敗時だけ使います。
• {base}assets/ 配下の ハッシュ付きアセット（ox-content-*-{hash}.css / .js）は cache-first です。
• クロスオリジンと GET 以外は無視します。

インストール時にサイト全体を事前キャッシュしません。ページは成功した ナビゲーションのあとでキャッシュに入ります。

ssg.siteUrl#

pwa を有効にしても ssg.siteUrl が無いと、ファイルは書かず、テーマ付き ページにもマニフェストリンクや登録スクリプトは付きません。ビルドは続き、 警告が出ます。

クライアント JavaScript#

offline を有効にすると（pwa オン時の既定）、テーマ付きページへ登録 スクリプトを注入します。

<script>
  if ("serviceWorker" in navigator) navigator.serviceWorker.register("/sw.js");
</script>

ベア出力（ssg.bare）にはリンクもスクリプトも付きません。siteUrl があれば ファイルは書くので、独自シェル側でワーカーを登録できます。

名前、色、URL はエスケープされるので、マニフェスト JSON や注入 HTML 属性から 抜け出せません。

関連#

• サイト生成
• Sitemap / robots / llms.txt
• 組み込み機能の概要
• 英語版ガイド