0
# Workbox SW
1

2
Workbox SW is a service worker library that provides an easy entry point to the Workbox ecosystem for Progressive Web Apps. It creates a global `workbox` object that acts as a proxy to dynamically load and access other Workbox modules, simplifying the integration of service worker functionality without requiring individual module management.
3

4
## Package Information
5

6
- **Package Name**: workbox-sw
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install workbox-sw`
10

11
## Core Imports
12

13
For service worker environments, import via `importScripts`:
14

15
```javascript
16
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.3.0/workbox-sw.js');
17
```
18

19
For module environments:
20

21
```javascript
22
import 'workbox-sw';
23
```
24

25
## Basic Usage
26

27
```javascript
28
// Import the library (creates global workbox object)
29
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.3.0/workbox-sw.js');
30

31
// Configure Workbox (optional)
32
workbox.setConfig({
33
  debug: true,
34
  modulePathPrefix: '/custom/path/to/workbox-modules/'
35
});
36

37
// Use Workbox modules through the global object
38
workbox.precaching.precacheAndRoute([
39
  '/app.js',
40
  '/styles.css',
41
  '/index.html'
42
]);
43

44
workbox.routing.registerRoute(
45
  new RegExp('.*\\.(?:png|jpg|jpeg|svg|gif)'),
46
  new workbox.strategies.CacheFirst({
47
    cacheName: 'image-cache',
48
    plugins: [
49
      new workbox.expiration.ExpirationPlugin({
50
        maxEntries: 50,
51
      }),
52
    ],
53
  })
54
);
55
```
56

57
## Architecture
58

59
Workbox SW is built around several key components:
60

61
- **Global Proxy Object**: The `workbox` global acts as a proxy that automatically loads Workbox modules on first access
62
- **Dynamic Module Loading**: Modules are loaded on-demand using `importScripts()` when their properties are accessed
63
- **CDN Integration**: By default, modules are loaded from Google's CDN, with options for custom paths
64
- **Configuration System**: Centralized configuration for debug mode, module paths, and loading behavior
65

66
## Capabilities
67

68
### Configuration
69

70
Configure Workbox behavior including debug mode and module loading paths.
71

72
```javascript { .api }
73
/**
74
 * Configure Workbox settings before accessing any modules
75
 * @param {Object} options - Configuration options
76
 * @param {boolean} options.debug - Use dev builds if true, prod builds if false (default: true on localhost)
77
 * @param {string} options.modulePathPrefix - Custom path prefix for module loading
78
 * @param {ModulePathCallback} options.modulePathCb - Custom callback for determining module paths
79
 */
80
workbox.setConfig(options);
81
```
82

83
### Manual Module Loading
84

85
Explicitly load Workbox modules to ensure availability.
86

87
```javascript { .api }
88
/**
89
 * Manually load a Workbox module by name
90
 * @param {string} moduleName - Name of the module to load (e.g., 'workbox-precaching')
91
 */
92
workbox.loadModule(moduleName);
93
```
94

95
### Dynamic Module Access
96

97
Access Workbox modules through property access on the global workbox object. Modules are loaded automatically on first access.
98

99
#### Background Sync
100

101
Access to workbox-background-sync module for offline background synchronization.
102

103
```javascript { .api }
104
workbox.backgroundSync
105
```
106

107
#### Broadcast Update
108

109
Access to workbox-broadcast-update module for notifying clients of cache updates.
110

111
```javascript { .api }
112
workbox.broadcastUpdate
113
```
114

115
#### Cacheable Response
116

117
Access to workbox-cacheable-response module for determining cacheable responses.
118

119
```javascript { .api }
120
workbox.cacheableResponse
121
```
122

123
#### Core
124

125
Access to workbox-core module providing fundamental Workbox utilities.
126

127
```javascript { .api }
128
workbox.core
129
```
130

131
#### Expiration
132

133
Access to workbox-expiration module for cache expiration management.
134

135
```javascript { .api }
136
workbox.expiration
137
```
138

139
#### Google Analytics
140

141
Access to workbox-google-analytics module for offline Google Analytics support.
142

143
```javascript { .api }
144
workbox.googleAnalytics
145
```
146

147
#### Navigation Preload
148

149
Access to workbox-navigation-preload module for navigation preload functionality.
150

151
```javascript { .api }
152
workbox.navigationPreload
153
```
154

155
#### Precaching
156

157
Access to workbox-precaching module for precaching static assets.
158

159
```javascript { .api }
160
workbox.precaching
161
```
162

163
#### Range Requests
164

165
Access to workbox-range-requests module for handling HTTP range requests.
166

167
```javascript { .api }
168
workbox.rangeRequests
169
```
170

171
#### Routing
172

173
Access to workbox-routing module for request routing and interception.
174

175
```javascript { .api }
176
workbox.routing
177
```
178

179
#### Strategies
180

181
Access to workbox-strategies module for caching strategies (CacheFirst, NetworkFirst, etc.).
182

183
```javascript { .api }
184
workbox.strategies
185
```
186

187
#### Streams
188

189
Access to workbox-streams module for handling streaming responses.
190

191
```javascript { .api }
192
workbox.streams
193
```
194

195
#### Recipes
196

197
Access to workbox-recipes module for common Workbox usage patterns.
198

199
```javascript { .api }
200
workbox.recipes
201
```
202

203
## Types
204

205
### ModulePathCallback
206

207
Custom callback function for determining module paths.
208

209
```javascript { .api }
210
/**
211
 * Callback function for customizing module paths
212
 * @callback ModulePathCallback
213
 * @param {string} moduleName - The name of the module to load (e.g., 'workbox-core')
214
 * @param {boolean} debug - When true, dev builds should be loaded, otherwise load prod builds
215
 * @returns {string} Path to the module file for importScripts()
216
 */
217
```
218

219
## Usage Examples
220

221
### Basic Service Worker Setup
222

223
```javascript
224
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.3.0/workbox-sw.js');
225

226
// Precache static assets
227
workbox.precaching.precacheAndRoute([
228
  '/index.html',
229
  '/app.js',
230
  '/styles.css'
231
]);
232

233
// Cache images with expiration
234
workbox.routing.registerRoute(
235
  /\.(?:png|jpg|jpeg|svg|gif)$/,
236
  new workbox.strategies.CacheFirst({
237
    cacheName: 'images',
238
    plugins: [
239
      new workbox.expiration.ExpirationPlugin({
240
        maxEntries: 60,
241
        maxAgeSeconds: 30 * 24 * 60 * 60, // 30 Days
242
      }),
243
    ],
244
  })
245
);
246
```
247

248
### Custom Configuration
249

250
```javascript
251
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.3.0/workbox-sw.js');
252

253
// Use custom module path
254
workbox.setConfig({
255
  debug: false,
256
  modulePathPrefix: '/custom/workbox-modules/'
257
});
258

259
// Or use a custom callback
260
workbox.setConfig({
261
  modulePathCb: (moduleName, debug) => {
262
    const suffix = debug ? 'dev' : 'prod';
263
    return `/my-cdn/${moduleName}.${suffix}.js`;
264
  }
265
});
266
```
267

268
### Preloading Modules
269

270
```javascript
271
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.3.0/workbox-sw.js');
272

273
// Preload modules that might be needed later
274
workbox.loadModule('workbox-background-sync');
275
workbox.loadModule('workbox-routing');
276

277
// Now these modules are available immediately
278
workbox.backgroundSync.Queue('my-queue');
279
```
280

281
## Error Handling
282

283
- **Configuration Error**: `setConfig()` throws an error if called after any modules have been loaded
284
- **Module Loading Error**: `loadModule()` logs a console error and re-throws if module loading fails
285
- **Network Errors**: Module loading failures typically indicate network issues or incorrect CDN paths
286

287
## Browser Support
288

289
- Designed specifically for service worker environments
290
- Requires support for ES6 Proxy objects
291
- Uses `importScripts()` for dynamic module loading
292
- Compatible with all modern browsers that support service workers