0
# Workbox Precaching
1
2
Workbox Precaching efficiently precaches assets for Progressive Web Apps (PWAs) and service workers. It provides a comprehensive API for caching resources during service worker installation and serving them from the cache to handle network requests, enabling reliable offline functionality and improved performance.
3
4
## Package Information
5
6
- **Package Name**: workbox-precaching
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install workbox-precaching`
10
11
## Core Imports
12
13
```typescript
14
import { precacheAndRoute, PrecacheController } from "workbox-precaching";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { precacheAndRoute, PrecacheController } = require("workbox-precaching");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { precacheAndRoute } from "workbox-precaching";
27
28
// Simple setup: precache assets and add route in one call
29
precacheAndRoute([
30
{ url: "/index.html", revision: "abc123" },
31
{ url: "/styles.css", revision: "def456" },
32
"/static/logo.png", // URLs without revision use the URL as the cache key
33
]);
34
35
// This is equivalent to:
36
// precache(entries);
37
// addRoute();
38
```
39
40
## Architecture
41
42
Workbox Precaching is built around several key components:
43
44
- **High-level Functions**: `precacheAndRoute()`, `precache()`, `addRoute()` for simple setup
45
- **Controller API**: `PrecacheController` class for fine-grained control over caching behavior
46
- **Route System**: `PrecacheRoute` and `PrecacheStrategy` for custom routing and caching strategies
47
- **Utility Functions**: Helper functions for cache key management and request matching
48
- **Plugin System**: Extensible architecture with `addPlugins()` and `PrecacheFallbackPlugin`
49
- **Cache Management**: Automatic cleanup of outdated caches and integrity checking
50
51
## Capabilities
52
53
### Simple Setup Functions
54
55
High-level functions for quick precaching setup that handle the most common use cases.
56
57
```typescript { .api }
58
function precacheAndRoute(
59
entries: Array<PrecacheEntry | string>,
60
options?: PrecacheRouteOptions
61
): void;
62
63
function precache(entries: Array<PrecacheEntry | string>): void;
64
65
function addRoute(options?: PrecacheRouteOptions): void;
66
```
67
68
[Simple Setup](./simple-setup.md)
69
70
### Advanced Controller
71
72
The `PrecacheController` class provides fine-grained control over precaching behavior with methods for installation, activation, and cache management.
73
74
```typescript { .api }
75
class PrecacheController {
76
constructor(options?: PrecacheControllerOptions);
77
78
precache(entries: Array<PrecacheEntry | string>): void;
79
install(event: ExtendableEvent): Promise<InstallResult>;
80
activate(event: ExtendableEvent): Promise<CleanupResult>;
81
}
82
```
83
84
[Advanced Controller](./advanced-controller.md)
85
86
### Route and Strategy Classes
87
88
Custom route and strategy classes for implementing specific caching behaviors and request handling patterns.
89
90
```typescript { .api }
91
class PrecacheRoute extends Route {
92
constructor(
93
precacheController: PrecacheController,
94
options?: PrecacheRouteOptions
95
);
96
}
97
98
class PrecacheStrategy extends Strategy {
99
constructor(options?: PrecacheStrategyOptions);
100
}
101
```
102
103
[Route and Strategy](./route-strategy.md)
104
105
### Utility Functions
106
107
Helper functions for cache key management, request matching, and handler creation.
108
109
```typescript { .api }
110
function getCacheKeyForURL(url: string): string | undefined;
111
112
function matchPrecache(request: string | Request): Promise<Response | undefined>;
113
114
function createHandlerBoundToURL(url: string): RouteHandlerCallback;
115
```
116
117
[Utilities](./utilities.md)
118
119
### Plugin and Cleanup
120
121
Plugin system for extending functionality and cleanup utilities for cache maintenance.
122
123
```typescript { .api }
124
function addPlugins(plugins: WorkboxPlugin[]): void;
125
126
function cleanupOutdatedCaches(): void;
127
128
class PrecacheFallbackPlugin implements WorkboxPlugin {
129
constructor(options: {
130
fallbackURL: string;
131
precacheController?: PrecacheController;
132
});
133
}
134
```
135
136
[Plugins and Cleanup](./plugins-cleanup.md)
137
138
## Core Types
139
140
```typescript { .api }
141
interface PrecacheEntry {
142
url: string;
143
revision?: string | null;
144
integrity?: string;
145
}
146
147
interface PrecacheRouteOptions {
148
directoryIndex?: string;
149
ignoreURLParametersMatching?: RegExp[];
150
cleanURLs?: boolean;
151
urlManipulation?: urlManipulation;
152
}
153
154
type urlManipulation = ({ url }: { url: URL }) => URL[];
155
156
interface InstallResult {
157
updatedURLs: string[];
158
notUpdatedURLs: string[];
159
}
160
161
interface CleanupResult {
162
deletedCacheRequests: string[];
163
}
164
165
interface PrecacheControllerOptions {
166
cacheName?: string;
167
plugins?: WorkboxPlugin[];
168
fallbackToNetwork?: boolean;
169
}
170
171
interface PrecacheStrategyOptions {
172
cacheName?: string;
173
plugins?: WorkboxPlugin[];
174
fetchOptions?: RequestInit;
175
matchOptions?: CacheQueryOptions;
176
fallbackToNetwork?: boolean;
177
}
178
```
179
180
## External Types
181
182
These types are imported from other Workbox packages:
183
184
```typescript { .api }
185
// From workbox-core
186
interface WorkboxPlugin {
187
cacheKeyWillBeUsed?: (options: any) => Promise<string> | string;
188
cacheWillUpdate?: (options: any) => Promise<Response | null> | Response | null;
189
cacheDidUpdate?: (options: any) => Promise<void> | void;
190
cachedResponseWillBeUsed?: (options: any) => Promise<Response | null> | Response | null;
191
requestWillFetch?: (options: any) => Promise<Request> | Request;
192
fetchDidSucceed?: (options: any) => Promise<Response> | Response;
193
fetchDidFail?: (options: any) => Promise<void> | void;
194
handlerWillStart?: (options: any) => Promise<void> | void;
195
handlerWillRespond?: (options: any) => Promise<Response> | Response;
196
handlerDidRespond?: (options: any) => Promise<void> | void;
197
handlerDidComplete?: (options: any) => Promise<void> | void;
198
handlerDidError?: (options: any) => Promise<Response | undefined> | Response | undefined;
199
}
200
201
type RouteHandlerCallback = (options: {
202
request: Request;
203
event: ExtendableEvent;
204
}) => Promise<Response> | Response;
205
206
// From workbox-routing
207
class Route {
208
constructor(match: any, handler: any, method?: string);
209
}
210
211
// From workbox-strategies
212
class Strategy {
213
constructor(options?: any);
214
}
215
```