You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<ahref="https://gitter.im/NekR/offline-plugin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><imgsrc="https://badges.gitter.im/NekR/offline-plugin.svg"alt="Join the chat at https://gitter.im/NekR/offline-plugin"></a>
11
10
</div>
12
11
<br>
13
12
14
13
This plugin is intended to provide an offline experience for **webpack** projects. It uses **ServiceWorker**, and **AppCache** as a fallback under the hood. Simply include this plugin in your ``webpack.config``, and the accompanying runtime in your client script, and your project will become offline ready by caching all (or some) of the webpack output assets.
15
14
16
15
<divalign="center">
17
-
<strong>Demo:<br><ahref="https://offline-plugin.now.sh/"> Progressive Web App built with <code>offline-plugin</code></a></strong><br>
16
+
<strong>Demo:<br><ahref="https://offline-plugin.now.sh/"> Progressive Web App built with <code>offline-plugin</code></a></strong><br>
When making a Singe Page Application, it's common to use [AppShell](https://medium.com/google-developers/instant-loading-web-apps-with-an-application-shell-architecture-7c0c2f10c73) model for it.
7
+
8
+
To make `offline-plugin` redirect all unknown navigation requests to a specific cache, specify `appShell` option, e.g. `appShell: '/'`.
9
+
10
+
### SSR
11
+
12
+
When using Server Side Rendering with AppShell model, make sure that you do not cache any server rendered data with it. Easiest way would be to make a route which will be serving the HTML file without any server rendered data in it (e.g. ready for client side rendering) and cache that route. Example: `appShell: '/app-shell.html'`
13
+
14
+
### Advanced
15
+
16
+
Previously, to achieve the same effect, `ServiceWorker.navigateFallbackURL` and `AppCache.FALLBACK` option had to be used. `ServiceWorker.navigateFallbackURL` is now deprecated and shouldn't be used at all. Instead, `appShell` should be used.
17
+
18
+
`appShell` is baked by `cacheMaps` option for `ServiceWorker` and `AppCache.FALLBACK` option for `AppCache`.
[Navigation preload](https://developers.google.com/web/updates/2017/02/navigation-preload) is a ServiceWorker's feature which provides a way to make a request to the website even before ServiceWorker or a page is initialized. This can be useful for data fetching to speedup loading of the application.
5
+
6
+
### Usage
7
+
8
+
In `offline-plugin`, _Navigation preload_ behaves differently for `cache-first` and `network-first` response strategies.
9
+
10
+
For `network-first` navigation preload is enabled by default and allows to fetch navigation pages ahead of time, even before ServiceWorker was initialized. To disabled it set `ServiceWorker.navigationPreload` option to `false`.
11
+
12
+
For `cache-first` navigation preload has to be enabled manually and also handled on the server side. To enabled navigation preload two functions has to be specified:
13
+
14
+
```js
15
+
ServiceWorker: {
16
+
navigationPreload: {
17
+
map: (url) => {
18
+
if (url.pathname==='/') {
19
+
return'/api/feed';
20
+
}
21
+
22
+
var post =url.pathname.match(/^\/post\/(\d+)$/);
23
+
24
+
if (post) {
25
+
return'/api/post/'+ post[1];
26
+
}
27
+
},
28
+
test: (url) => {
29
+
if (url.pathname.indexOf('/api/') ===0) {
30
+
returntrue;
31
+
}
32
+
}
33
+
},
34
+
}
35
+
```
36
+
37
+
*`map` function is used to map navigation preload request to other requests, e.g. API requests.
38
+
*`test` function is used to test for possible consumers of navigation preload mapping
39
+
40
+
In previous example `map` function maps navigation preload of `/` to `/api/feed`. Then when a request to `/api/feed` happens, `test` function is used to determine that such request might be preloaded with _navigation preload_ (it checks if `pathname` of the request starts with `/api/`).
41
+
42
+
#### Server Side
43
+
44
+
When a navigation preload request happens, it contains `Service-Worker-Navigation-Preload: true` header. Server side should use this header to detect the preload and send different content to such request.
45
+
46
+
Express.js example:
47
+
48
+
```js
49
+
functionserveIndex(req, res) {
50
+
if (req.headers['service-worker-navigation-preload']) {
@@ -16,37 +23,45 @@ Allows you to define what to cache and how.
16
23
17
24
#### `publicPath: string`
18
25
19
-
Same as`webpack`'s `output.publicPath` option. Useful to specify or override `publicPath` specifically for `offline-plugin`. When not specified, `webpack`'s `output.publicPath` value is used. When `webpack`'s `output.publicPath`value isn't specified, relative paths are used (see `relativePaths` option).
26
+
Similar to`webpack`'s `output.publicPath` option. Useful to specify or override `publicPath` specifically for `offline-plugin`. When not specified, `webpack`'s `output.publicPath` value is used. When `publicPath` value isn't spsecified at all (either by this option or by `webpack`'s `output.publicPath`option), relative paths are used (see `relativePaths` option).
Response strategy. Whether to use a cache or network first for responses.
34
+
35
+
With `'cache-first'` all request are sent to consult the cache first and if the cache is empty, request is sent to the network.
36
+
37
+
With `'network-first'` all request are sent to the network first and if network request fails consult the cache as a fallback.
27
38
> Default: `'cache-first'`.
28
39
29
40
#### `updateStrategy: 'changed' | 'all'`
30
41
Cache update strategy. [More details about `updateStrategy`](update-strategies.md)
42
+
**Please, do not change this option unless you're sure you know what you're doing.**
31
43
> Default: `'changed'`.
32
44
33
45
#### `externals: Array<string>`
34
-
Allows you to specify _external_ assets (assets which aren't generated by webpack) that should be included in the cache. If you don't change the `caches` configuration option then it should be enough to simply add assets to this (`externals`) option. For other details and more advanced use cases see [`caches` docs](caches.md).
46
+
47
+
Allows you to specify additional (external to the build process) URLs to be cached.
Excludes matched assets from being added to the [caches](https://github.com/NekR/offline-plugin#caches-all--object). Exclusion is performed before [_rewrites_](https://github.com/NekR/offline-plugin/blob/master/docs/options.md#rewrites-function--object) happens.
41
54
[Learn more about assets _rewrite_](rewrites.md)
42
55
43
-
> Default: `['**/.*', '**/*.map']`
44
-
> _Excludes all files which start with `.` or end with `.map`_
56
+
> Default: `['**/.*', '**/*.map', '**/*.gz']`
57
+
> _Excludes all files which start with `.` or end with `.map` or `.gz`_
45
58
46
59
#### `relativePaths: boolean`
47
60
When set to `true`, all the asset paths generated in the cache will be relative to the `ServiceWorker` file or the `AppCache` folder location respectively.
48
-
`publicPath` option is ignored when this is **explicitly** set to `true`.
49
-
> **Default:**`true`
61
+
62
+
This option is ignored when `publicPath` is set.
63
+
`publicPath` option is ignored when this option is set **explicitly** to `true`.
Version of the cache. Can be a function, which is useful in _watch-mode_ when you need to apply dynamic value.
@@ -58,7 +73,10 @@ Version of the cache. Can be a function, which is useful in _watch-mode_ when yo
58
73
59
74
#### `rewrites: Function | Object`
60
75
61
-
Rewrite function or rewrite map (`Object`). Useful when assets are served in a different way from the client perspective, e.g. usually `index.html` is served as `/`.
76
+
Provides a way to rewrite final representation of the file on the server.
77
+
Useful when assets are served in a different way from the client perspective, e.g. usually `/index.html` is served as `/`.
78
+
79
+
Can be either a function or an `Object`.
62
80
63
81
[See more about `rewrites` option and default function](rewrites.md)
64
82
@@ -68,7 +86,7 @@ See [documentation of `cacheMaps`](cache-maps.md) for syntax and usage examples
68
86
69
87
#### `autoUpdate: true | number`
70
88
71
-
Enables automatic updates of ServiceWorker and AppCache. If set to `true`, it uses default interval of _1 hour_. Set a `number` value to have provide custom update interval.
89
+
Enables automatic updates of ServiceWorker and AppCache. If set to `true`, it uses default interval of _1 hour_. Set a `number` value to provide custom update interval.
72
90
73
91
_**Note:** Please note that if user has multiple opened tabs of your website then update may happen more often because each opened tab will have its own interval for updates._
74
92
@@ -80,66 +98,72 @@ _**Note:** Please note that if user has multiple opened tabs of your website the
80
98
81
99
Settings for the `ServiceWorker` cache. Use `null` or `false` to disable `ServiceWorker` generation.
82
100
83
-
*`output`: `string`. Relative (from the _webpack_'s config `output.path`) output path for emitted script.
101
+
***`output`**: `string`. Relative (from the _webpack_'s config `output.path`) output path for emitted script.
84
102
_Default:_`'sw.js'`
85
103
86
-
*`entry`: `string`. Relative or absolute path to the file which will be used as the `ServiceWorker` entry/bootstrapping. Useful to implement additional features or handlers for Service Worker events such as `push`, `sync`, etc.
104
+
***`entry`**: `string`. Relative or absolute path to the file which will be used as the `ServiceWorker` entry/bootstrapping. Useful to implement additional features or handlers for Service Worker events such as `push`, `sync`, etc.
*`cacheName`: `string`. **This option is very dangerous. Touching it you must realize that you should **not** change it after you go production. Changing it may corrupt the cache and leave old caches on users' devices. This option is useful when you need to run more than one project on _the same domain_.
110
+
***`cacheName`**: `string`. **This option is very dangerous.** This option should **not** be changed at all after you deploy `ServiceWorker` to production. Changing it may corrupt the cache and leave old caches on users' devices.
111
+
112
+
This option is useful when you need to run more than one project on _the same domain_.
93
113
_Default:__`''`_ (empty string)
94
114
_Example:_`'my-project'`
95
115
96
-
*`navigateFallbackURL`: `string`. The URL that should be returned from the cache when a requested navigation URL isn't available on the cache or network. Similar to the `AppCache.FALLBACK` option.
97
-
_Example:_`navigateFallbackURL: '/'`
98
-
99
-
*`navigateFallbackForRedirects`: `boolean`. If this flag is false `navigateFallbackURL` will not be used for 3xx responses. (By default it will be used for all non 2xx navigate responses).
100
-
_Example:_`navigateFallbackForRedirects: false`
101
-
_Default:_`true`
102
-
103
-
*`events`: `boolean`. Enables runtime events for the ServiceWorker. For supported events see `Runtime`'s `install()` options.
116
+
***`events`**: `boolean`. Enables runtime events for the ServiceWorker. For supported events see [`Runtime`](runtime.md)'s `install()` options.
104
117
_Default:_`false`
105
118
106
-
*`publicPath`: `string`. Provides a way to override `ServiceWorker`'s script file location on the server. Should be an exact path to the generated `ServiceWorker` file.
119
+
***`publicPath`**: `string`. Provides a way to override `ServiceWorker`'s script file location on the server. Should be an exact path to the generated `ServiceWorker` file.
*`prefetchRequest`: `Object`. Provides a way to specify [request init options](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request) for pre-fetch requests (pre-cache requests on `install` event). Allowed options: `credentials`, `headers`, `mode`, `cache`.
127
+
***`prefetchRequest`**: `Object`. Provides a way to specify [request init options](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request) for pre-fetch requests (pre-cache requests on `install` event). Allowed options: `credentials`, `headers`, `mode`, `cache`.
111
128
_Default:_`{ credentials: 'omit', mode: 'cors' }`
112
-
_Example:_`{ credentials: 'same-origin' }`
129
+
_Example:_`{ credentials: 'include' }`
113
130
114
-
*`minify`: `boolean`. If set to `true` or `false`, the `ServiceWorker`'s output will be minified or not accordingly. If set to something else, the `ServiceWorker` output will be minified **if** you are using`webpack.optimize.UglifyJsPlugin` in your configuration.
131
+
***`minify`**: `boolean`. If set to `true` or `false`, the `ServiceWorker`'s output will be minified or not accordingly. If set to something else, the `ServiceWorker` output will be minified **if** you are using `webpack.optimize.UglifyJsPlugin` in your configuration.
115
132
_Default:_`null`
116
133
134
+
***[Deprecated]**`navigateFallbackURL`: `string`. The URL that should be returned from the cache when a requested navigation URL isn't available on the cache or network. Similar to the `AppCache.FALLBACK` option.
135
+
_Example:_`navigateFallbackURL: '/'`
136
+
137
+
***[Deprecated]**`navigateFallbackForRedirects`: `boolean`. If this flag is false `navigateFallbackURL` will not be used for 3xx responses. (By default it will be used for all non 2xx navigate responses).
138
+
_Example:_`navigateFallbackForRedirects: false`
139
+
_Default:_`true`
140
+
117
141
#### `AppCache: Object | null | false`
118
142
119
143
Settings for the `AppCache` cache. Use `null` or `false` to disable `AppCache` generation.
120
144
121
145
> _**Warning**_: Officially the AppCache feature [has been deprecated](https://developer.mozilla.org/en-US/docs/Web/HTML/Using_the_application_cache) in favour of Service Workers. However, Service Workers are still being implemented across all browsers (you can track progress [here](https://jakearchibald.github.io/isserviceworkerready/)) so AppCache is unlikely to suddenly disappear. Therefore please don't be afraid to use the AppCache feature if you have a need to provide offline support to browsers that do not support Service Workers, but it is good to be aware of this fact and make a deliberate decision on your configuration.
122
146
123
-
*`directory`: `string`. Relative (from the _webpack_'s config `output.path`) output directly path for the `AppCache` emitted files.
147
+
***`directory`**: `string`. Relative (from the _webpack_'s config `output.path`) output directly path for the `AppCache` emitted files.
*`FALLBACK`: `Object`. Reflects `AppCache`'s `FALLBACK` section. Useful for single page applications making use of HTML5 routing or for displaying custom _Offline page_.
153
+
***`FALLBACK`**: `Object`. Reflects `AppCache`'s `FALLBACK` section. Useful for single page applications making use of HTML5 routing or for displaying custom _Offline page_.
130
154
_Example 1:_`{ '/blog': '/' }` will map all requests starting with `/blog` to the domain roboto when request fails.
131
155
_Example 2:_`{ '/': '/offline-page.html' }` will return contents of `/offline-page.html` for any failed request.
132
156
_Default:_`null`
133
157
134
-
*`events`: `boolean`. Enables runtime events for AppCache. For supported events see `Runtime`'s `install()` options.
158
+
***`events`**: `boolean`. Enables runtime events for AppCache. For supported events see [`Runtime`](runtime.md)'s `install()` options.
135
159
_Default:_`false`
136
160
137
-
*`publicPath`: `string`. Provides a way to override `AppCache`'s folder location on the server. Should be exact path to the generated `AppCache` folder.
161
+
***`publicPath`**: `string`. Provides a way to override `AppCache`'s folder location on the server. Should be exact path to the generated `AppCache` folder.
138
162
_Default:_`null`
139
163
_Example:_`'my/new/path/appcache'`
140
164
141
-
*`disableInstall` :`boolean`. Disable the automatic installation of the `AppCache` when calling to `runtime.install()`. Useful when you to specify `<html manifest="...">` attribute manually (to cache every page user visits).
165
+
***`disableInstall`**: `boolean`. Disable the automatic installation of the `AppCache` when calling `runtime.install()`. Useful when you want to specify `<html manifest="...">` attribute manually (to cache every page user visits).
142
166
_Default:_`false`
143
167
144
-
*`includeCrossOrigin` :`boolean`. Outputs cross-origin URLs into `AppCache`'s manifest file. **Cross-origin URLs aren't supported in `AppCache` when used on HTTPS.**
168
+
***`includeCrossOrigin`**: `boolean`. Outputs cross-origin URLs into `AppCache`'s manifest file. **Cross-origin URLs aren't supported in `AppCache` when used on HTTPS.**
0 commit comments