Service workers
Service Worker は、アプリ内部でネットワークリクエストを処理するプロキシサーバーとして機能します。これによりアプリをオフラインで動作させることが可能になります。もしオフラインサポートが不要な場合(または構築するアプリの種類によって現実的に実装できない場合)でも、ビルドした JS と CSS を事前にキャッシュしてナビゲーションを高速化するために Service Worker を使用する価値はあります。
SvelteKit では、src/service-worker.js
ファイル (や src/service-worker/index.js
) がある場合、バンドルされ、自動的に登録されます。必要に応じて、service worker の ロケーション を変更することができます。
service worker を独自のロジックで登録する必要がある場合や、その他のソリューションを使う場合は、自動登録を無効化 することができます。デフォルトの登録方法は次のようなものです:
if ('serviceWorker' in var navigator: Navigator
navigator) {
function addEventListener<"load">(type: "load", listener: (this: Window, ev: Event) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)
addEventListener('load', function () {
var navigator: Navigator
navigator.Navigator.serviceWorker: ServiceWorkerContainer
Available only in secure contexts.
serviceWorker.ServiceWorkerContainer.register(scriptURL: string | URL, options?: RegistrationOptions): Promise<ServiceWorkerRegistration>
register('./path/to/service-worker.js');
});
}
service worker の内部では
service worker の内部では、$service-worker
モジュール にアクセスでき、これによって全ての静的なアセット、ビルドファイル、プリレンダリングページへのパスが提供されます。また、アプリのバージョン文字列 (一意なキャッシュ名を作成するのに使用できます) と、デプロイメントの base
パスが提供されます。Vite の設定に define
(グローバル変数の置換に使用) を指定している場合、それはサーバー/クライアントのビルドだけでなく、service worker にも適用されます。
次の例では、ビルドされたアプリと static
にあるファイルをすぐに(eagerly)キャッシュし、その他全てのリクエストはそれらの発生時にキャッシュします。これにより、各ページは一度アクセスするとオフラインで動作するようになります。
/// <reference types="@sveltejs/kit" />
import { const build: string[]
An array of URL strings representing the files generated by Vite, suitable for caching with cache.addAll(build)
.
During development, this is an empty array.
build, const files: string[]
An array of URL strings representing the files in your static directory, or whatever directory is specified by config.kit.files.assets
. You can customize which files are included from static
directory using config.kit.serviceWorker.files
files, const version: string
See config.kit.version
. It’s useful for generating unique cache names inside your service worker, so that a later deployment of your app can invalidate old caches.
version } from '$service-worker';
// Create a unique cache name for this deployment
const const CACHE: string
CACHE = `cache-${const version: string
See config.kit.version
. It’s useful for generating unique cache names inside your service worker, so that a later deployment of your app can invalidate old caches.
version}`;
const const ASSETS: string[]
ASSETS = [
...const build: string[]
An array of URL strings representing the files generated by Vite, suitable for caching with cache.addAll(build)
.
During development, this is an empty array.
build, // the app itself
...const files: string[]
An array of URL strings representing the files in your static directory, or whatever directory is specified by config.kit.files.assets
. You can customize which files are included from static
directory using config.kit.serviceWorker.files
files // everything in `static`
];
var self: Window & typeof globalThis
self.function addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void (+1 overload)
Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options’s capture.
When set to true, options’s capture prevents callback from being invoked when the event’s eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event’s eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event’s eventPhase attribute value is AT_TARGET.
When set to true, options’s passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
When set to true, options’s once indicates that the callback will only be invoked once after which the event listener will be removed.
If an AbortSignal is passed for options’s signal, then the event listener will be removed when signal is aborted.
The event listener is appended to target’s event listener list and is not appended if it has the same type, callback, and capture.
addEventListener('install', (event: Event
event) => {
// Create a new cache and add all files to it
async function function (local function) addFilesToCache(): Promise<void>
addFilesToCache() {
const const cache: Cache
cache = await var caches: CacheStorage
Available only in secure contexts.
caches.CacheStorage.open(cacheName: string): Promise<Cache>
open(const CACHE: string
CACHE);
await const cache: Cache
cache.Cache.addAll(requests: Iterable<RequestInfo>): Promise<void> (+1 overload)
addAll(const ASSETS: string[]
ASSETS);
}
event: Event
event.waitUntil(function (local function) addFilesToCache(): Promise<void>
addFilesToCache());
});
var self: Window & typeof globalThis
self.function addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void (+1 overload)
Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options’s capture.
When set to true, options’s capture prevents callback from being invoked when the event’s eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event’s eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event’s eventPhase attribute value is AT_TARGET.
When set to true, options’s passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
When set to true, options’s once indicates that the callback will only be invoked once after which the event listener will be removed.
If an AbortSignal is passed for options’s signal, then the event listener will be removed when signal is aborted.
The event listener is appended to target’s event listener list and is not appended if it has the same type, callback, and capture.
addEventListener('activate', (event: Event
event) => {
// Remove previous cached data from disk
async function function (local function) deleteOldCaches(): Promise<void>
deleteOldCaches() {
for (const const key: string
key of await var caches: CacheStorage
Available only in secure contexts.
caches.CacheStorage.keys(): Promise<string[]>
keys()) {
if (const key: string
key !== const CACHE: string
CACHE) await var caches: CacheStorage
Available only in secure contexts.
caches.CacheStorage.delete(cacheName: string): Promise<boolean>
delete(const key: string
key);
}
}
event: Event
event.waitUntil(function (local function) deleteOldCaches(): Promise<void>
deleteOldCaches());
});
var self: Window & typeof globalThis
self.function addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void (+1 overload)
Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options’s capture.
When set to true, options’s capture prevents callback from being invoked when the event’s eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event’s eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event’s eventPhase attribute value is AT_TARGET.
When set to true, options’s passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
When set to true, options’s once indicates that the callback will only be invoked once after which the event listener will be removed.
If an AbortSignal is passed for options’s signal, then the event listener will be removed when signal is aborted.
The event listener is appended to target’s event listener list and is not appended if it has the same type, callback, and capture.
addEventListener('fetch', (event: Event
event) => {
// ignore POST requests etc
if (event: Event
event.request.method !== 'GET') return;
async function function (local function) respond(): Promise<Response>
respond() {
const const url: URL
url = new var URL: new (url: string | URL, base?: string | URL) => URL
The URL interface represents an object providing static methods used for creating object URLs.
URL
class is a global reference for require('url').URL
https://nodejs.org/api/url.html#the-whatwg-url-api
URL(event: Event
event.request.url);
const const cache: Cache
cache = await var caches: CacheStorage
Available only in secure contexts.
caches.CacheStorage.open(cacheName: string): Promise<Cache>
open(const CACHE: string
CACHE);
// `build`/`files` can always be served from the cache
if (const ASSETS: string[]
ASSETS.Array<string>.includes(searchElement: string, fromIndex?: number): boolean
Determines whether an array includes a certain element, returning true or false as appropriate.
includes(const url: URL
url.URL.pathname: string
pathname)) {
const const response: Response | undefined
response = await const cache: Cache
cache.Cache.match(request: RequestInfo | URL, options?: CacheQueryOptions): Promise<Response | undefined>
match(const url: URL
url.URL.pathname: string
pathname);
if (const response: Response | undefined
response) {
return const response: Response
response;
}
}
// for everything else, try the network first, but
// fall back to the cache if we're offline
try {
const const response: Response
response = await function fetch(input: string | URL | globalThis.Request, init?: RequestInit): Promise<Response> (+1 overload)
fetch(event: Event
event.request);
// if we're offline, fetch can return a value that is not a Response
// instead of throwing - and we can't pass this non-Response to respondWith
if (!(const response: Response
response instanceof var Response: {
new (body?: BodyInit | null, init?: ResponseInit): Response;
prototype: Response;
error(): Response;
json(data: any, init?: ResponseInit): Response;
redirect(url: string | URL, status?: number): Response;
}
This Fetch API interface represents the response to a request.
Response)) {
throw new var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error('invalid response from fetch');
}
if (const response: Response
response.Response.status: number
status === 200) {
const cache: Cache
cache.Cache.put(request: RequestInfo | URL, response: Response): Promise<void>
put(event: Event
event.request, const response: Response
response.Response.clone(): Response
clone());
}
return const response: Response
response;
} catch (function (local var) err: unknown
err) {
const const response: Response | undefined
response = await const cache: Cache
cache.Cache.match(request: RequestInfo | URL, options?: CacheQueryOptions): Promise<Response | undefined>
match(event: Event
event.request);
if (const response: Response | undefined
response) {
return const response: Response
response;
}
// if there's no cache, then just error out
// as there is nothing we can do to respond to this request
throw function (local var) err: unknown
err;
}
}
event: Event
event.respondWith(function (local function) respond(): Promise<Response>
respond());
});
キャッシュにはご注意ください! 場合によっては、オフラインでは利用できないデータよりも古くなったデータのほうが悪いことがあります。ブラウザはキャッシュが一杯になると空にするため、ビデオファイルのような大きなアセットをキャッシュする場合にもご注意ください。
開発中は(During development)
service worker はプロダクション向けにはバンドルされますが、開発中はバンドルされません。そのため、modules in service workers をサポートするブラウザのみ、開発時にもそれを使用することができます。service worker を手動で登録する場合、開発時に { type: 'module' }
オプションを渡す必要があります:
import { const dev: boolean
Whether the dev server is running. This is not guaranteed to correspond to NODE_ENV
or MODE
.
dev } from '$app/environment';
var navigator: Navigator
navigator.Navigator.serviceWorker: ServiceWorkerContainer
Available only in secure contexts.
serviceWorker.ServiceWorkerContainer.register(scriptURL: string | URL, options?: RegistrationOptions): Promise<ServiceWorkerRegistration>
register('/service-worker.js', {
RegistrationOptions.type?: WorkerType | undefined
type: const dev: boolean
Whether the dev server is running. This is not guaranteed to correspond to NODE_ENV
or MODE
.
dev ? 'module' : 'classic'
});
build
とprerendered
は開発中は空配列です
型安全性(Type safety)
service worker に適切な型を設定するには、マニュアルで設定が必要です。service-worker.js
の中で、ファイルの先頭に以下を追加してください:
/// <reference types="@sveltejs/kit" />
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />
const sw = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (self));
/// <reference types="@sveltejs/kit" />
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />
const sw = self as unknown as ServiceWorkerGlobalScope;
これにより、HTMLElement
のような service worker の中では使用できない DOM の型付けへのアクセスが無効になり、正しい global が初期化されます。self
を sw
に再代入することで、プロセス内で型をキャストすることができます (いくつか方法がありますが、これが追加のファイルを必要としない最も簡単な方法です)。ファイルの残りの部分では、self
の代わりに sw
を使用します。SvelteKit の型を参照することで、$service-worker
import に適切な型定義があることを保証することができます。もし $env/static/public
をインポートする場合は、そのインポートに // @ts-ignore
を追加するか、/// <reference types="../.svelte-kit/ambient.d.ts" />
を reference types に追加する必要があります。
その他のソリューション
SvelteKit の service worker 実装は意図的に低レベル(low-level)です。より本格的な、よりこだわりが強い(opinionated)ソリューションが必要な場合は、Vite PWA plugin のようなソリューションをご覧になることをおすすめしております、こちらは Workbox を使用しています。service worker に関する一般的な情報をもっとお探しであれば、MDN web docs をおすすめします。