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