|
`offline-plugin` for webpack
[![npm](https://img.shields.io/npm/v/offline-plugin.svg?maxAge=3600&v4)](https://www.npmjs.com/package/offline-plugin)
[![npm](https://img.shields.io/npm/dm/offline-plugin.svg?maxAge=3600)](https://www.npmjs.com/package/offline-plugin)
[![Join the chat at https://gitter.im/NekR/offline-plugin](https://badges.gitter.im/NekR/offline-plugin.svg)](https://gitter.im/NekR/offline-plugin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|
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.
[Demo] Progressive Web App built with offline-plugin
Install
npm install offline-plugin [--save-dev]
Setup
First, instantiate the plugin with options in your webpack.config
:
var OfflinePlugin = require('offline-plugin');
module.exports = {
plugins: [
new OfflinePlugin()
]
}
Then, add the runtime into your entry file (typically main entry):
require('offline-plugin/runtime').install();
Docs
Articles
Options
All options are optional and offline-plugin
can be used without specifying them. Also see full list of default options here.
caches: 'all' | Object
Allows you to define what to cache and how.
'all'
: means that everything (all the webpack output assets) and URLs listed in externals
option will be cached on install.Object
: Object with 3 possible Array<string>
sections (properties): main
, additional
, optional
. All sections are optional and by default are empty (no assets added).
More details about caches
Default: 'all'
.
publicPath: string
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).
Examples:
publicPath: '/project/'
publicPath: 'https://example.com/project'
responseStrategy: 'cache-first' | 'network-first'
Response strategy. Whether to use a cache or network first for responses.
Default: 'cache-first'
.
updateStrategy: 'changed' | 'all'
Cache update strategy. More details about updateStrategy
Default: 'changed'
.
externals: Array<string>
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.
Default: null
Example value: ['fonts/roboto.woff']
excludes: Array<string | globs_pattern>
Excludes matched assets from being added to the caches. Exclusion is performed before rewrite happens.
Learn more about assets rewrite
Default: ['**/.*', '**/*.map']
Excludes all files which start with .
or end with .map
relativePaths: boolean
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.
publicPath
option is ignored when this is explicitly set to true
.
Default: true
version: string | (plugin: OfflinePlugin) => void
Version of the cache. Can be a function, which is useful in watch-mode when you need to apply dynamic value.
Function
is called with the plugin instance as the first argumentstring
which can be interpolated with [hash]
token
Default: Current date
rewrites: Function | Object
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 /
.
See more about rewrites
option and default function
cacheMaps: Array<Object>
See documentation of cacheMaps
for syntax and usage examples
autoUpdate: true | number
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.
Note: Please not 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.
Default: false
Example: true
Example: 1000 * 60 * 60 * 5
(five hours)
ServiceWorker: Object | null | false
Settings for the ServiceWorker
cache. Use null
or false
to disable ServiceWorker
generation.
-
output
: string
. Relative (from the webpack's config output.path
) output path for emitted script.
Default: 'sw.js'
-
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.
Default: empty file
-
scope
: string
. Reflects ServiceWorker.register's scope
option.
Default: null
-
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.
Default: ''
(empty string)
Example: 'my-project'
-
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.
Example: navigateFallbackURL: '/'
-
events
: boolean
. Enables runtime events for the ServiceWorker. For supported events see Runtime
's install()
options.
Default: false
-
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.
Default: null
Example: 'my/new/path/sw.js'
-
prefetchRequest
: Object
. Provides a way to specify request init options for pre-fetch requests (pre-cache requests on install
event). Allowed options: credentials
, headers
, mode
, cache
.
Default: { credentials: 'omit', mode: 'cors' }
Example: { credentials: 'same-origin' }
AppCache: Object | null | false
Settings for the AppCache
cache. Use null
or false
to disable AppCache
generation.
Warning: Officially the AppCache feature has been deprecated in favour of Service Workers. However, Service Workers are still being implemented across all browsers (you can track progress here) 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.
-
directory
: string
. Relative (from the webpack's config output.path
) output directly path for the AppCache
emitted files.
Default: 'appcache/'
-
NETWORK
: string
. Reflects AppCache
's NETWORK
section.
Default: '*'
-
FALLBACK
: Object
. Reflects AppCache
's FALLBACK
section. Useful for single page applications making use of HTML5 routing or for displaying custom Offline page.
Example 1: { '/blog': '/' }
will map all requests starting with /blog
to the domain roboto when request fails.
Example 2: { '/': '/offline-page.html' }
will return contents of /offline-page.html
for any failed request.
Default: null
-
events
: boolean
. Enables runtime events for AppCache. For supported events see Runtime
's install()
options.
Default: false
-
publicPath
: string
. Provides a way to override AppCache
's folder location on the server. Should be exact path to the generated AppCache
folder.
Default: null
Example: 'my/new/path/appcache'
-
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).
Default: false
-
includeCrossOrigin
:boolean
. Outputs cross-origin URLs into AppCache
's manifest file. Cross-origin URLs aren't supported in AppCache
when used on HTTPS.
Default: false
Who is using offline-plugin
Projects
PWAs
If you are using offline-plugin
, feel free to submit a PR to add your project to this list.
Like offline-plugin
?
Support it by giving feedback, contributing or just by 🌟 starring the project!
License
MIT
CHANGELOG
CHANGELOG