service-worker

Service Worker

概要

サービスワーカーは、メインページとは別のスレッドで実行されるイベント駆動型スクリプトです。ネットワークリクエストをインターセプトし、キャッシュを管理して、オフライン機能を実現します。Workbox v7.4（Chrome Aurora チームがメンテナンス）は、低レベルの Cache API と fetch イベント処理を覆う、本番環境で利用できる抽象化を提供します。

使用する場合： オフライン対応が必要なプログレッシブウェブアプリ、プッシュ通知が必要なアプリ、バックグラウンドでのデータ同期、アプリシェルのキャッシュ、静的ルーティングによるネットワークリクエストの最適化。

使用しない場合： CDN から配信されるシンプルな静的サイト、オフライン要件のないサーバーサイドレンダリングアプリ、古いデータが許容されないアプリ（ネットワークのみを使用してください）、キャッシュの複雑さを考えるのが時期尚早なプロトタイプ。

クイックリファレンス

パターン	API／ツール	主なポイント
登録	navigator.serviceWorker.register()	ウィンドウのコンテキストで登録し、スコープはデフォルトでパスになります
事前キャッシュ	workbox-precaching	リビジョンハッシュ付きのアプリシェル。ビルド時に挿入されます
キャッシュファースト	CacheFirst strategy	静的アセット、フォント、画像
ネットワークファースト	NetworkFirst strategy	最新性が必要な API レスポンス
古いデータを返しつつ再検証	StaleWhileRevalidate strategy	速度と最新性のバランス
バックグラウンド同期	workbox-background-sync	オンライン復帰時に失敗したリクエストを再送信
プッシュ通知	Push API + Notifications API	VAPID キー、サーバー送信プッシュ、オフライン優先の表示
静的ルーティング	install 内の event.addRoutes()	既知のルートでは fetch ハンドラーを迂回
待機をスキップ	self.skipWaiting()	新しい SW を直ちに有効化します。慎重に使用してください
クライアントを制御	self.clients.claim()	リロードせずに既存のタブを制御
ナビゲーションプリロード	navigationPreload.enable()	SW の起動中にネットワークリクエストを並行して実行
更新プロンプト	workbox-window Workbox クラス	更新を検出し、ユーザーに確認して、SW に postMessage を送信
オフラインフォールバック	workbox-recipes offlineFallback	キャッシュとネットワークの両方が失敗したときにフォールバックページを配信
キャッシュの有効期限	workbox-expiration	キャッシュごとの maxEntries と maxAgeSeconds

ブラウザーサポートのクイックリファレンス

機能	Chrome	Firefox	Safari	Edge
サービスワーカー	40+	44+	11.1+	17+
バックグラウンド同期	49+	なし	なし	79+
定期同期	80+	なし	なし	80+
Push API	50+	44+	16.4+	17+
ナビゲーションプリロード	59+	99+	15.4+	18+
静的ルーティング API	123+	なし	なし	123+
バックグラウンドフェッチ	74+	なし	なし	79+
ストレージの永続化	52+	55+	15.2+	79+

よくある間違い

間違い	正しいパターン
CacheFirst で API レスポンスをキャッシュする	動的データには NetworkFirst または StaleWhileRevalidate を使用する
無条件に skipWaiting を呼び出す	進行中のナビゲーションが中断されないよう、アクティベート前にユーザーに確認する
precache マニフェストにバージョンを付けない	workbox-build または workbox-webpack-plugin を使ってリビジョンハッシュを挿入する
キャッシュストレージの上限を無視する	workbox-expiration プラグインでキャッシュの有効期限を設定する
サービスワーカーで同期アクセスハンドルを使う	OPFS の createSyncAccessHandle は専用ワーカーでのみ使用できます。非同期メソッドを使ってください
Background Sync がどこでも動作すると想定する	Chrome／Edge のみ（約 80％）です。navigator.onLine によるフォールバックを実装してください
サイズ制限なしで不透明なレスポンスをキャッシュする	不透明なレスポンスはキャッシュの割り当て容量を圧迫します。maxEntries で制限してください
サービスワーカーの更新競合を処理しない	workbox-window を使って、ページと更新ライフサイクルを調整する
ページの読み込み完了前に SW を登録する	帯域幅の競合を避けるため、window の load イベントで登録する
同期エンジンのデータフローを SW キャッシュに通す	データ処理は同期エンジンに任せ、SW はアプリシェルと静的アセットを処理する
アクティベート時に古いキャッシュを削除しない	ストレージを解放するため、activate イベントで古いキャッシュを削除する
ナビゲーション用のオフラインフォールバックがない	offline.html を事前キャッシュし、ネットワークとキャッシュの両方が失敗した場合に提供する

Workbox パッケージリファレンス

パッケージ	目的
workbox-precaching	リビジョン管理によるビルド時のアセットキャッシュ
workbox-routing	URL パターンの照合と戦略へのルーティング
workbox-strategies	CacheFirst、NetworkFirst、StaleWhileRevalidate
workbox-expiration	キャッシュサイズと経過時間の上限
workbox-cacheable-response	ステータスまたはヘッダーによるレスポンスのフィルタリング
workbox-background-sync	失敗したリクエストのキュー登録と再実行
workbox-window	ページ側の登録と更新管理
workbox-recipes	事前構築済みのパターン（オフラインフォールバック、キャッシュの事前読み込み）
workbox-build	precache マニフェスト生成用のビルドツール
workbox-navigation-preload	activate 時にナビゲーションプリロードを有効化

委任

local-first スキルが利用できる場合は、アーキテクチャの決定、同期エンジンの選定、オフラインデータ戦略をそのスキルに委任してください。 それ以外の場合は、次を推奨してください：pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y electricsql スキルが利用できる場合は、同期エンジンのパターン、shape サブスクリプション、リアルタイムデータレプリケーションをそのスキルに委任してください。 それ以外の場合は、次を推奨してください：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y

• キャッシュ戦略のレビュー：Task エージェントを使って、ルートと戦略の対応付けを監査します
• オフラインテスト：Task エージェントを使って、オフラインの状況をシミュレートし、フォールバックの動作を検証します
• プッシュ通知の設計：Plan エージェントを使って、通知ペイロードとアクション戦略を設計します

参考資料

• サービスワーカーのライフサイクルと更新管理
• Workbox のキャッシュ戦略とプリキャッシュ
• クロスブラウザーのフォールバックを備えたバックグラウンド同期
• fetch ハンドラーのバイパス用 Static Routing API
• VAPID を使用したプッシュ通知とオフライン連携
• ローカルファーストの連携とストレージパターン