0
# Plugin Configuration
1
2
The `OfflinePlugin` class provides extensive configuration options for customizing offline behavior, caching strategies, and asset management.
3
4
## Plugin Constructor
5
6
```javascript { .api }
7
class OfflinePlugin {
8
constructor(options?: PluginOptions);
9
apply(compiler: webpack.Compiler): void;
10
static defaultOptions: PluginOptions;
11
}
12
```
13
14
Create a new OfflinePlugin instance with optional configuration.
15
16
**Import:**
17
```javascript
18
const OfflinePlugin = require('offline-plugin');
19
```
20
21
**Parameters:**
22
- `options` (optional): Configuration object with plugin settings
23
24
## Core Configuration Options
25
26
### Basic Options
27
28
```javascript { .api }
29
interface PluginOptions {
30
caches?: 'all' | CacheConfiguration;
31
publicPath?: string;
32
updateStrategy?: 'changed' | 'all';
33
responseStrategy?: 'cache-first' | 'network-first';
34
externals?: string[];
35
excludes?: string[];
36
relativePaths?: boolean;
37
version?: string | Function;
38
autoUpdate?: boolean | number;
39
rewrites?: Function | Object;
40
safeToUseOptionalCaches?: boolean;
41
}
42
```
43
44
**`caches`** (default: `'all'`)
45
Defines which assets to cache. Set to `'all'` to cache all webpack output assets, or provide detailed cache configuration.
46
47
**`publicPath`** (default: webpack's `output.publicPath`)
48
The base URL for all cached assets. Override webpack's publicPath setting.
49
50
**`updateStrategy`** (default: `'changed'`)
51
- `'changed'`: Only update when assets change
52
- `'all'`: Update all assets when any asset changes
53
54
**`responseStrategy`** (default: `'cache-first'`)
55
- `'cache-first'`: Check cache first, fallback to network
56
- `'network-first'`: Try network first, fallback to cache
57
58
**`externals`** (default: `[]`)
59
Array of external URLs to cache alongside webpack assets.
60
61
```javascript
62
externals: [
63
'/static/img/logo.png',
64
'https://fonts.googleapis.com/css?family=Roboto'
65
]
66
```
67
68
**`excludes`** (default: `['**/.*', '**/*.map', '**/*.gz']`)
69
Glob patterns for assets to exclude from caching.
70
71
**`relativePaths`** (default: auto-detected)
72
Generate relative paths in cache manifest instead of absolute URLs.
73
74
**`version`** (default: current timestamp)
75
Cache version identifier. Can be string or function returning string.
76
77
**`autoUpdate`** (default: `false`)
78
Enable automatic update checking. Set to `true` for 1-hour interval, or number for custom milliseconds.
79
80
**`rewrites`** (default: function that handles index.html rewriting)
81
Function or object for rewriting asset paths in the cache manifest. Useful for handling SPA routing.
82
83
**`safeToUseOptionalCaches`** (default: `false`)
84
Set to `true` to suppress warnings when using `additional` and `optional` cache sections. Only enable if assets have unique names with hashes.
85
86
### Advanced Cache Configuration
87
88
```javascript { .api }
89
interface CacheConfiguration {
90
main?: string[];
91
additional?: string[];
92
optional?: string[];
93
}
94
```
95
96
**`main`** - Essential assets loaded on first visit
97
**`additional`** - Assets cached but not required for basic functionality
98
**`optional`** - Assets cached opportunistically
99
100
Special cache keys:
101
- `':rest:'` - Include all remaining uncategorized assets
102
- `':externals:'` - Include all external URLs
103
104
```javascript
105
caches: {
106
main: ['index.html', 'main.js', 'main.css'],
107
additional: [':rest:'],
108
optional: [':externals:']
109
}
110
```
111
112
### App Shell Configuration
113
114
```javascript { .api }
115
interface PluginOptions {
116
appShell?: string;
117
cacheMaps?: CacheMap[];
118
}
119
120
interface CacheMap {
121
match: string | Function;
122
to?: string | Function;
123
requestTypes?: ('navigate' | 'same-origin' | 'cross-origin')[];
124
}
125
```
126
127
**`appShell`**
128
HTML file to return for all navigation requests (Single Page Application pattern).
129
130
**`cacheMaps`**
131
URL rewriting rules for request routing.
132
133
```javascript
134
appShell: '/app-shell.html',
135
cacheMaps: [
136
{
137
match: /^\/api\/.*$/,
138
to: '/offline-api-fallback.json',
139
requestTypes: ['same-origin']
140
}
141
]
142
```
143
144
## ServiceWorker Configuration
145
146
```javascript { .api }
147
interface ServiceWorkerOptions {
148
output?: string;
149
entry?: string;
150
scope?: string;
151
events?: boolean;
152
minify?: boolean;
153
forceInstall?: boolean;
154
updateViaCache?: 'imports' | 'all' | 'none';
155
prefetchRequest?: PrefetchRequestOptions;
156
navigationPreload?: boolean | 'auto';
157
}
158
159
interface PrefetchRequestOptions {
160
credentials?: 'same-origin' | 'include' | 'omit';
161
headers?: { [key: string]: string };
162
mode?: 'cors' | 'no-cors' | 'same-origin';
163
cache?: string;
164
}
165
```
166
167
**`output`** (default: `'sw.js'`)
168
ServiceWorker file name.
169
170
**`entry`** (default: webpack generated entry)
171
Entry point file for the ServiceWorker. Used to customize ServiceWorker logic.
172
173
**`scope`** (default: same as publicPath)
174
ServiceWorker registration scope.
175
176
**`events`** (default: `false`)
177
Enable runtime event callbacks.
178
179
**`minify`** (default: based on webpack mode)
180
Enable/disable ServiceWorker code minification. Can be boolean or minification options object.
181
182
**`forceInstall`** (default: `false`)
183
Force ServiceWorker installation even on insecure origins (not recommended for production).
184
185
**`updateViaCache`** (default: `'imports'`)
186
Controls how the browser's HTTP cache is used when checking for ServiceWorker updates:
187
- `'imports'`: Check cache for imported scripts only
188
- `'all'`: Check cache for ServiceWorker and all imported scripts
189
- `'none'`: Bypass cache for all ServiceWorker-related requests
190
191
**`navigationPreload`** (default: `'auto'`)
192
Enable navigation preload for faster page loads.
193
194
**`prefetchRequest`**
195
Default options for prefetch requests.
196
197
```javascript
198
ServiceWorker: {
199
output: 'service-worker.js',
200
scope: '/app/',
201
events: true,
202
navigationPreload: true,
203
prefetchRequest: {
204
credentials: 'same-origin',
205
mode: 'cors'
206
}
207
}
208
```
209
210
## AppCache Configuration
211
212
```javascript { .api }
213
interface AppCacheOptions {
214
directory?: string;
215
NETWORK?: string;
216
FALLBACK?: { [path: string]: string };
217
caches?: string[];
218
events?: boolean;
219
disableInstall?: boolean;
220
includeCrossOrigin?: boolean;
221
}
222
```
223
224
**`NETWORK`** (default: `'*'`)
225
Network allowlist entries.
226
227
**`FALLBACK`**
228
Fallback mappings for offline pages.
229
230
**`directory`** (default: `'appcache/'`)
231
Output directory for AppCache manifest.
232
233
```javascript
234
AppCache: {
235
directory: 'cache/',
236
NETWORK: '*',
237
FALLBACK: {
238
'/': '/offline.html'
239
},
240
events: true
241
}
242
```
243
244
## Static Properties
245
246
```javascript { .api }
247
class OfflinePlugin {
248
static defaultOptions: PluginOptions;
249
}
250
```
251
252
Access default configuration values for reference or extension.
253
254
## Usage Examples
255
256
### Basic Configuration
257
```javascript
258
new OfflinePlugin({
259
responseStrategy: 'network-first',
260
externals: ['/favicon.ico']
261
})
262
```
263
264
### Advanced Configuration
265
```javascript
266
new OfflinePlugin({
267
caches: {
268
main: ['index.html', 'main.js'],
269
additional: ['**/*.css'],
270
optional: [':externals:']
271
},
272
updateStrategy: 'changed',
273
appShell: '/shell.html',
274
ServiceWorker: {
275
events: true,
276
navigationPreload: true
277
},
278
autoUpdate: 1000 * 60 * 30 // 30 minutes
279
})
280
```
281
282
### Development Configuration
283
```javascript
284
new OfflinePlugin({
285
excludes: ['**/*.map', '**/*.hot-update.*'],
286
relativePaths: true,
287
ServiceWorker: {
288
minify: false
289
}
290
})
291
```