12k
All articles

Service WorkerをES Moduleとして記述する

Service WorkerをESモジュールへ移行する方法を解説。静的インポート、コード共有、ビルド設定、更新キャッシュ、旧ブラウザー向けの代替策を紹介します。

OpenReplay Team
OpenReplay Team
Service WorkerをES Moduleとして記述する

Service WorkerをES Moduleとして実行するには、navigator.serviceWorker.register('/sw.js', { type: 'module' }) を呼び出します。このオプションを指定しない場合、ブラウザーはファイルをクラシックスクリプトとして読み込むため、import や export は構文エラーになります。

多くのチームは同じような経緯でこの問題に行き着きます。アプリはすべてESMで書かれ、Viteでビルドされているのに、Service Workerだけはクラシックスクリプトのままです。そして手作業でコピーした設定ファイルを importScripts() で読み込み、その設定ファイルはいつの間にかアプリ側とずれていきます。Workerをモジュールに切り替えればこの問題は解消しますが、モジュールWorkerには独自のルールがあります。また、主要ブラウザーのサポートが出揃ったのはFirefox 147になってからです。本記事では、登録方法の変更、ページとのコード共有、モジュールWorkerが動作しなくなる原因となるルール、更新時の挙動、ビルド出力、フォールバックについて解説します。ライフサイクルの基本については、A Practical Guide to Service Workersを参照してください。

重要なポイント

  • register() に { type: 'module' } を渡すと、Service WorkerはES Moduleとして動作します。デフォルトのtypeは 'classic' です。
  • モジュールWorkerで importScripts() を呼び出すと TypeError がスローされます。そのため、すべての呼び出しを静的な import に置き換える必要があります。
  • Service Workerでは動的 import() もimport mapsも使えません。すべての指定子(specifier)は、ビルド時点で実在するURLに解決されている必要があります。
  • モジュールService Workerは、Chrome・Edge 91以降、Safari 15以降、Firefox 147以降で動作します。
  • デフォルトの updateViaCache: 'imports' 設定では、更新チェック時にインポートされたモジュールがHTTPキャッシュから返されることがあります。共有モジュールにはハッシュ付きURLを使うか、キャッシュ有効期間を短く設定してください。

Service WorkerをES Moduleに切り替えるには

Service WorkerをES Moduleに切り替えるには、2つの変更が必要です。登録時に type オプションを渡すことと、importScripts() を import に置き換えることです。MDNの register() リファレンスによると、type には 'classic'(デフォルト)または 'module' を指定できます。

以下はクラシック版です。

// config.js (classic)
self.CACHE_NAME = 'app-v3';

// sw.js (classic)
importScripts('/config.js');
console.log(self.CACHE_NAME);

こちらはモジュール版です。

// config.js (module)
export const CACHE_NAME = 'app-v3';

// sw.js (module)
import { CACHE_NAME } from './config.js';
console.log(CACHE_NAME);

MDNの Worker() コンストラクターのページでモジュールWorkerについて説明されているとおり、モジュールスクリプトはCORSで読み込まれ、strictモードで実行されます。また、text/javascript などのJavaScript MIMEタイプで配信する必要があります。

ページとWorkerでコードを共有する

Service WorkerをES Moduleとして書く最大の理由は、1つのモジュールをページとWorkerの両方で使えることです。キャッシュ名とプリキャッシュ対象のリストを1つのファイルにまとめます。

// config.js
export const CACHE_NAME = 'app-v3';
export const PRECACHE_URLS = ['/', '/index.html', '/offline.html'];

Workerは両方の値をインポートし、標準的なCache APIの呼び出しで利用します。

// sw.js
import { CACHE_NAME, PRECACHE_URLS } from './config.js';

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
  );
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
});

ページ側も同じファイルをインポートします。

// main.js, loaded via <script type="module">
import { CACHE_NAME } from './config.js';

console.debug('Expected cache:', CACHE_NAME);
navigator.serviceWorker.register('/sw.js', { type: 'module' });

これで、バージョン文字列を1か所で更新するだけで、ページとWorkerの両方に変更が反映されます。

モジュールService Workerが動作しなくなる3つのルール

クラシックなService WorkerをES Moduleに移行する際の失敗の大半は、次の3つのルールに起因します。

  1. importScripts() は使えない。 HTML仕様の importScripts() の処理手順では、グローバルスコープのtypeが "module" の場合に TypeError をスローすると定められています。また、MDNの importScripts() リファレンスでは、モジュールWorkerでは代わりに import を使うよう案内されています。Workerが importScripts() 経由でライブラリを読み込んでいる場合は、そのライブラリのESMビルドが必要です。
  2. 動的 import() は使えない。 MDNの ServiceWorker のページによると、仕様上Service Workerでの動的 import() は禁止されており、呼び出すと例外がスローされます。条件付きで必要になるコードも、あらかじめ静的インポートで読み込んでおきましょう。
  3. import mapsは使えない。 import mapsはService Worker内では適用されません。Workerでのimport mapsのサポートは、現在もオープンな提案(whatwg/html #8173)の段階です。すべての指定子は相対URLまたは絶対URLである必要があります。'idb' のような裸の名前(bare specifier)はモジュール指定子として解決されないため、ビルドステップで書き換えるかインライン化する必要があります。

インポートしたモジュールがService Workerの更新に与える影響

モジュールService Workerでは、インポートされたモジュールも更新チェックの対象になります。Chromeによるモジュール Service Worker の発表記事にあるとおり、importScripts() の依存関係と同様に、config.js のような静的インポートされたファイルが変更されると、sw.js 自体に変更がなくても更新フローが開始されることがあります。

これらのチェックでHTTPキャッシュを使用できるかどうかは、updateViaCache オプションで決まります。

値メインスクリプトインポートされたモジュール
'imports'(デフォルト)常にネットワークから取得HTTPキャッシュを許可
'all'HTTPキャッシュを許可HTTPキャッシュを許可
'none'常にネットワークから取得常にネットワークから取得

デフォルト設定では、ハッシュなしのURLから長い max-age で配信される共有モジュールは、更新チェックを経ても古いまま残る可能性があります。対策としては、共有モジュールをコンテンツハッシュ付きURLで配信する、キャッシュ有効期間を短くする、updateViaCache: 'none' で登録する、といった方法があります。デプロイ後も古いUIのままのユーザーや、すでに存在しないハッシュ付きアセットへのリクエストがセッションリプレイで見つかった場合、この種の更新バグが原因であることがよくあります。どのバージョンのWorkerが制御しているかを確認する方法については、Service Workerのデバッグを参照してください。

ビルドツール:バンドルしないESMか、単一ファイルか

Viteでは、Service Workerも他の出力ファイルと同様に扱われます。ただし、/sw.js のようなハッシュなしの固定URLに、独立したエントリーとして出力する必要があります。ビルドごとにURLが変わると、登録のたびに異なるスクリプトを指すことになるためです。Viteのpublic ディレクトリはファイルを加工せずにそのままコピーするため、手書きのWorkerには適していますが、Worker内のインポートは解決されません。

モジュールService Workerのビルド方法は2通りあります。

  • バンドルしないESM。 sw.js と共有モジュールを、URL指定子を持つ個別のファイルとして配信し、type: 'module' で登録します。各インポートは個別にフェッチされ、更新チェックの対象になります。
  • 単一のバンドルファイル。 バンドラーが、bare specifierで指定されたパッケージも含めてすべてを1つのスクリプトにインライン化します。出力に import 文が含まれていなければクラシックWorkerとしても動作するため、これをフォールバックとして利用できます。

モジュール非対応ブラウザー向けのフォールバック

caniuseに掲載されているMDN browser-compat-dataによると、主要な4つのエンジンはすべてモジュールService Workerをサポートしています。

ブラウザーtype: 'module' に対応した最初のバージョン
Chrome91
Edge91
Safari(macOSおよびiOS)15
Firefox147(Firefox 147のリリースノートによる)

クラシック版のビルドが必要になるのは、Chrome・Edge 90以前、Safari 14.1以前、Firefox 146以前といった古いブラウザーだけです。w3c/ServiceWorker #1582の機能検出に関するリクエストからもわかるように、モジュールサポートを検出する標準APIは存在しません。古いブラウザーは type オプションを事前に拒否するのではなく、スクリプトをダウンロードして評価に失敗した時点で register() がrejectされます。このrejectはcatchできます。

async function registerSW() {
  if (!('serviceWorker' in navigator)) return;
  try {
    return await navigator.serviceWorker.register('/sw.js', { type: 'module' });
  } catch (err) {
    console.warn('Module service worker failed, falling back to classic:', err);
    return navigator.serviceWorker.register('/sw-classic.js');
  }
}

このtry/catchによるフォールバックには2つのデメリットがあります。1つは、古いブラウザーが使われることのないモジュールスクリプトを無駄にダウンロードすることです。もう1つは、対応ブラウザーでモジュールWorkerに本当のエラーがあった場合も catch で握りつぶされてしまうことです。そのため、フォールバックする前にエラーをログに記録しておきましょう。

まとめ

Service Workerのモジュール化は、type オプションと3つのルール(静的インポートのみ、importScripts() 不可、bare specifier不可)に集約されます。まずは、Workerとページで重複している定数を1つの共有モジュールにまとめ、{ type: 'module' } で登録してください。そのうえで、共有モジュールがどのようにキャッシュされるかを確認し、変更が更新チェックを通じてユーザーに確実に届くようにしましょう。

よくある質問

モジュールService Workerでトップレベルawaitは使えますか?

使えません。installやfetchなどのリスナーを確実に登録できるよう、初回の評価は同期的に完了する必要があるため、Service Workerではトップレベルawaitが禁止されています。Chromiumでは、登録がTypeErrorでrejectされます。awaitが静的インポートされたモジュール内にある場合も同様です。モジュールグラフ全体が非同期になってしまうためです。非同期の初期化処理は、event.waitUntil()でラップしたinstallまたはactivateハンドラーに移してください。

既存のService Workerを同じURLのままクラシックからモジュールに切り替えると、更新がトリガーされますか?

はい。Service Worker仕様では、スクリプトのURLや内容がまったく同じでも、Workerのtypeが変わった場合は更新として扱われます。既存のクラシック登録に対してregister('/sw.js', { type: 'module' })を呼び出すと、新しいWorkerがインストールされ、通常のwaitingおよびactivationのライフサイクルをたどります。なお、URL、type、updateViaCacheの値がすべて同じregister()呼び出しは、何もフェッチせずにresolveされます。

モジュールService WorkerからCDNや別オリジンのモジュールをインポートできますか?

はい、相手側のオリジンが許可していれば可能です。モジュールのインポートはCORSでフェッチされるため、クロスオリジンのモジュールは、自分のオリジンを許可するAccess-Control-Allow-Originヘッダー付きで配信されている必要があります。そうでない場合はインポートが失敗し、register()がrejectされます。クラシックのimportScripts()はno-corsモードでスクリプトを読み込むため、この条件は不要です。なお、Service Workerのスクリプト自体は、引き続き登録元のページと同一オリジンである必要があります。

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — self-hosted, with full data ownership.

Star on GitHub

We use cookies to improve your experience. By using our site, you accept cookies.