0
# Virtual Module Registration
1

2
Framework-specific service worker registration modules that provide seamless integration with React, Vue, Svelte, SolidJS, Preact, and vanilla JavaScript applications.
3

4
## Capabilities
5

6
### Vanilla JavaScript Registration
7

8
Basic service worker registration for vanilla JavaScript and non-reactive applications.
9

10
```typescript { .api }
11
// Virtual module: virtual:pwa-register
12
/**
13
 * Registers the service worker and returns an update function
14
 * @param options - Registration options including callbacks for SW events
15
 * @returns Promise-based function to trigger service worker updates
16
 */
17
function registerSW(options?: RegisterSWOptions): (reloadPage?: boolean) => Promise<void>;
18

19
interface RegisterSWOptions {
20
  immediate?: boolean;
21
  onNeedRefresh?: () => void;
22
  onOfflineReady?: () => void;
23
  onRegistered?: (registration?: ServiceWorkerRegistration) => void;
24
  onRegisteredSW?: (swScriptUrl: string, registration?: ServiceWorkerRegistration) => void;
25
  onRegisterError?: (error: any) => void;
26
}
27
```
28

29
**Usage Example:**
30

31
```typescript
32
import { registerSW } from "virtual:pwa-register";
33

34
const updateSW = registerSW({
35
  immediate: true,
36
  onNeedRefresh() {
37
    if (confirm("New content available. Reload?")) {
38
      updateSW(true);
39
    }
40
  },
41
  onOfflineReady() {
42
    console.log("App ready to work offline");
43
  },
44
  onRegisterError(error) {
45
    console.error("SW registration error", error);
46
  },
47
});
48
```
49

50
### React Hook Registration
51

52
React hook-based service worker registration with state management.
53

54
```typescript { .api }
55
// Virtual module: virtual:pwa-register/react
56
/**
57
 * React hook for service worker registration with reactive state
58
 * @param options - Registration options
59
 * @returns Object with reactive state and update function
60
 */
61
function useRegisterSW(options?: RegisterSWOptions): {
62
  needRefresh: [boolean, Dispatch<SetStateAction<boolean>>];
63
  offlineReady: [boolean, Dispatch<SetStateAction<boolean>>];
64
  updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
65
};
66
```
67

68
**Usage Example:**
69

70
```tsx
71
import React from "react";
72
import { useRegisterSW } from "virtual:pwa-register/react";
73

74
function PWABadge() {
75
  const {
76
    needRefresh: [needRefresh, setNeedRefresh],
77
    offlineReady: [offlineReady, setOfflineReady], 
78
    updateServiceWorker,
79
  } = useRegisterSW({
80
    onRegisteredSW(swUrl, r) {
81
      console.log(`Service Worker at: ${swUrl}`);
82
    },
83
    onRegisterError(error) {
84
      console.log("SW registration error", error);
85
    },
86
  });
87

88
  const close = () => {
89
    setOfflineReady(false);
90
    setNeedRefresh(false);
91
  };
92

93
  return (
94
    <div className="pwa-toast" role="alert">
95
      {(offlineReady || needRefresh) && (
96
        <div className="pwa-message">
97
          {offlineReady ? (
98
            <span>App ready to work offline</span>
99
          ) : (
100
            <span>New content available, click to update.</span>
101
          )}
102
          <div>
103
            {needRefresh && (
104
              <button onClick={() => updateSW(true)}>Reload</button>
105
            )}
106
            <button onClick={close}>Close</button>
107
          </div>
108
        </div>
109
      )}
110
    </div>
111
  );
112
}
113
```
114

115
### Vue Composable Registration
116

117
Vue 3 composable for service worker registration with reactive refs.
118

119
```typescript { .api }
120
// Virtual module: virtual:pwa-register/vue
121
/**
122
 * Vue composable for service worker registration with reactive state
123
 * @param options - Registration options
124
 * @returns Object with reactive refs and update function
125
 */
126
function useRegisterSW(options?: RegisterSWOptions): {
127
  needRefresh: Ref<boolean>;
128
  offlineReady: Ref<boolean>;
129
  updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
130
};
131
```
132

133
**Usage Example:**
134

135
```vue
136
<template>
137
  <div v-if="offlineReady || needRefresh" class="pwa-toast" role="alert">
138
    <div class="message">
139
      <span v-if="offlineReady">App ready to work offline</span>
140
      <span v-else>New content available, click to update.</span>
141
    </div>
142
    <div class="buttons">
143
      <button v-if="needRefresh" @click="updateServiceWorker(true)">
144
        Reload
145
      </button>
146
      <button @click="close">Close</button>
147
    </div>
148
  </div>
149
</template>
150

151
<script setup>
152
import { useRegisterSW } from "virtual:pwa-register/vue";
153

154
const { needRefresh, offlineReady, updateServiceWorker } = useRegisterSW({
155
  onRegisteredSW(swUrl, r) {
156
    console.log(`Service Worker at: ${swUrl}`);
157
  },
158
  onRegisterError(error) {
159
    console.log("SW registration error", error);
160
  },
161
});
162

163
function close() {
164
  offlineReady.value = false;
165
  needRefresh.value = false;
166
}
167
</script>
168
```
169

170
### Svelte Store Registration
171

172
Svelte store-based service worker registration with writable stores.
173

174
```typescript { .api }
175
// Virtual module: virtual:pwa-register/svelte
176
/**
177
 * Svelte store-based service worker registration
178
 * @param options - Registration options
179
 * @returns Object with writable stores and update function
180
 */
181
function useRegisterSW(options?: RegisterSWOptions): {
182
  needRefresh: Writable<boolean>;
183
  offlineReady: Writable<boolean>;
184
  updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
185
};
186
```
187

188
**Usage Example:**
189

190
```svelte
191
<script>
192
  import { useRegisterSW } from "virtual:pwa-register/svelte";
193

194
  const { needRefresh, offlineReady, updateServiceWorker } = useRegisterSW({
195
    onRegisteredSW(swUrl, r) {
196
      console.log(`Service Worker at: ${swUrl}`);
197
    },
198
    onRegisterError(error) {
199
      console.log("SW registration error", error);
200
    },
201
  });
202

203
  function close() {
204
    $offlineReady = false;
205
    $needRefresh = false;
206
  }
207
</script>
208

209
{#if $offlineReady || $needRefresh}
210
  <div class="pwa-toast" role="alert">
211
    <div class="message">
212
      {#if $offlineReady}
213
        <span>App ready to work offline</span>
214
      {:else}
215
        <span>New content available, click to update.</span>
216
      {/if}
217
    </div>
218
    <div class="buttons">
219
      {#if $needRefresh}
220
        <button on:click={() => updateServiceWorker(true)}>Reload</button>
221
      {/if}
222
      <button on:click={close}>Close</button>
223
    </div>
224
  </div>
225
{/if}
226
```
227

228
### SolidJS Signal Registration
229

230
SolidJS signal-based service worker registration with accessor/setter pairs.
231

232
```typescript { .api }
233
// Virtual module: virtual:pwa-register/solid
234
/**
235
 * SolidJS signal-based service worker registration
236
 * @param options - Registration options  
237
 * @returns Object with signal accessor/setter pairs and update function
238
 */
239
function useRegisterSW(options?: RegisterSWOptions): {
240
  needRefresh: [Accessor<boolean>, Setter<boolean>];
241
  offlineReady: [Accessor<boolean>, Setter<boolean>];
242
  updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
243
};
244
```
245

246
**Usage Example:**
247

248
```tsx
249
import { Component, Show } from "solid-js";
250
import { useRegisterSW } from "virtual:pwa-register/solid";
251

252
const PWABadge: Component = () => {
253
  const {
254
    needRefresh: [needRefresh, setNeedRefresh],
255
    offlineReady: [offlineReady, setOfflineReady],
256
    updateServiceWorker,
257
  } = useRegisterSW({
258
    onRegisteredSW(swUrl, r) {
259
      console.log(`Service Worker at: ${swUrl}`);
260
    },
261
    onRegisterError(error) {
262
      console.log("SW registration error", error);
263
    },
264
  });
265

266
  const close = () => {
267
    setOfflineReady(false);
268
    setNeedRefresh(false);
269
  };
270

271
  return (
272
    <Show when={offlineReady() || needRefresh()}>
273
      <div class="pwa-toast" role="alert">
274
        <div class="message">
275
          <Show
276
            when={offlineReady()}
277
            fallback={<span>New content available, click to update.</span>}
278
          >
279
            <span>App ready to work offline</span>
280
          </Show>
281
        </div>
282
        <div class="buttons">
283
          <Show when={needRefresh()}>
284
            <button onClick={() => updateServiceWorker(true)}>Reload</button>
285
          </Show>
286
          <button onClick={close}>Close</button>
287
        </div>
288
      </div>
289
    </Show>
290
  );
291
};
292
```
293

294
### Preact Hook Registration
295

296
Preact hook-based service worker registration with state updaters.
297

298
```typescript { .api }
299
// Virtual module: virtual:pwa-register/preact
300
/**
301
 * Preact hook for service worker registration with state management
302
 * @param options - Registration options
303
 * @returns Object with state values/updaters and update function
304
 */
305
function useRegisterSW(options?: RegisterSWOptions): {
306
  needRefresh: [boolean, StateUpdater<boolean>];
307
  offlineReady: [boolean, StateUpdater<boolean>];
308
  updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
309
};
310
```
311

312
**Usage Example:**
313

314
```tsx
315
import { h } from "preact";
316
import { useRegisterSW } from "virtual:pwa-register/preact";
317

318
function PWABadge() {
319
  const {
320
    needRefresh: [needRefresh, setNeedRefresh],
321
    offlineReady: [offlineReady, setOfflineReady],
322
    updateServiceWorker,
323
  } = useRegisterSW({
324
    onRegisteredSW(swUrl, r) {
325
      console.log(`Service Worker at: ${swUrl}`);
326
    },
327
    onRegisterError(error) {
328
      console.log("SW registration error", error);
329
    },
330
  });
331

332
  const close = () => {
333
    setOfflineReady(false);
334
    setNeedRefresh(false);
335
  };
336

337
  return (
338
    (offlineReady || needRefresh) && (
339
      <div className="pwa-toast" role="alert">
340
        <div className="message">
341
          {offlineReady ? (
342
            <span>App ready to work offline</span>
343
          ) : (
344
            <span>New content available, click to update.</span>
345
          )}
346
        </div>
347
        <div className="buttons">
348
          {needRefresh && (
349
            <button onClick={() => updateServiceWorker(true)}>Reload</button>
350
          )}
351
          <button onClick={close}>Close</button>
352
        </div>
353
      </div>
354
    )
355
  );
356
}
357
```
358

359
## Registration Options
360

361
### Service Worker Registration Configuration
362

363
Common options available across all framework integrations.
364

365
```typescript { .api }
366
interface RegisterSWOptions {
367
  /** Register service worker immediately on load */
368
  immediate?: boolean;
369
  /** Called when new content is available and user confirmation is needed */
370
  onNeedRefresh?: () => void;
371
  /** Called when app is ready to work offline */
372
  onOfflineReady?: () => void;
373
  /** 
374
   * Called after service worker registration (deprecated)
375
   * @deprecated Use onRegisteredSW instead
376
   */
377
  onRegistered?: (registration?: ServiceWorkerRegistration) => void;
378
  /** Called after service worker registration with SW URL and registration */
379
  onRegisteredSW?: (swScriptUrl: string, registration?: ServiceWorkerRegistration) => void;
380
  /** Called when service worker registration fails */
381
  onRegisterError?: (error: any) => void;
382
}
383
```
384

385
### Update Service Worker Function
386

387
Function signature for triggering service worker updates across all frameworks.
388

389
```typescript { .api }
390
/**
391
 * Triggers service worker update and page reload
392
 * @param reloadPage - Whether to reload page after update (deprecated parameter)
393
 * @returns Promise that resolves when update is complete
394
 */
395
type UpdateServiceWorker = (reloadPage?: boolean) => Promise<void>;
396
```
397

398
## Virtual Module Access Patterns
399

400
### Import Patterns
401

402
Different ways to import virtual modules based on your setup:
403

404
```typescript
405
// Standard imports
406
import { registerSW } from "virtual:pwa-register";
407
import { useRegisterSW } from "virtual:pwa-register/react";
408
import { useRegisterSW } from "virtual:pwa-register/vue";
409

410
// With type imports
411
import type { RegisterSWOptions } from "virtual:pwa-register";
412
import type { RegisterSWOptions } from "virtual:pwa-register/react";
413

414
// Re-exported from main package
415
import type { RegisterSWOptions } from "vite-plugin-pwa";
416
```
417

418
### Conditional Registration
419

420
Pattern for conditional service worker registration:
421

422
```typescript
423
import { registerSW } from "virtual:pwa-register";
424

425
if ("serviceWorker" in navigator) {
426
  const updateSW = registerSW({
427
    immediate: false,
428
    onNeedRefresh() {
429
      // Show update prompt to user
430
      showUpdatePrompt(() => updateSW(true));
431
    },
432
    onOfflineReady() {
433
      // Notify user app works offline
434
      showOfflineNotification();
435
    },
436
  });
437
}
438
```