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 (Source of the PWA)
npm install offline-plugin [--save-dev]
First, instantiate the plugin with options in your webpack.config:
// webpack.config.js example
var OfflinePlugin = require('offline-plugin');
module.exports = {
// ...
plugins: [
// ... other plugins
// it always better if OfflinePlugin is the last plugin added
new OfflinePlugin()
]
// ...
}Then, add the runtime into your entry file (typically main entry):
require('offline-plugin/runtime').install();All options are optional and offline-plugin can be used without specifying them. Also see full list of default options here.
Allows you to define what to cache and how.
'all': means that everything (all the webpack output assets) and URLs listed inexternalsoption will be cached on install.Object: Object with 3 possibleArray<string>sections (properties):main,additional,optional. All sections are optional and by default are empty (no assets added).
Default:
'all'.
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'
Response strategy. Whether to use a cache or network first for responses.
Default:
'cache-first'.
Cache update strategy. More details about updateStrategy
Default:
'changed'.
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 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
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 of the cache. Can be a function, which is useful in watch-mode when you need to apply dynamic value.
Functionis called with the plugin instance as the first argumentstringwhich can be interpolated with[hash]token
Default: Current date
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
See documentation of cacheMaps for syntax and usage examples
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 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.
Default:
false
Example:true
Example:1000 * 60 * 60 * 5(five hours)
Settings for the ServiceWorker cache. Use null or false to disable ServiceWorker generation.
-
output:string. Relative (from the webpack's configoutput.path) output path for emitted script.
Default:'sw.js' -
entry:string. Relative or absolute path to the file which will be used as theServiceWorkerentry/bootstrapping. Useful to implement additional features or handlers for Service Worker events such aspush,sync, etc.
Default: empty file -
scope:string. Reflects ServiceWorker.register'sscopeoption.
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 theAppCache.FALLBACKoption.
Example:navigateFallbackURL: '/' -
events:boolean. Enables runtime events for the ServiceWorker. For supported events seeRuntime'sinstall()options. Default:false -
publicPath:string. Provides a way to overrideServiceWorker's script file location on the server. Should be an exact path to the generatedServiceWorkerfile. Default:nullExample:'my/new/path/sw.js' -
prefetchRequest:Object. Provides a way to specify request init options for pre-fetch requests (pre-cache requests oninstallevent). Allowed options:credentials,headers,mode,cache.
Default:{ credentials: 'omit', mode: 'cors' }
Example:{ credentials: 'same-origin' }
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 configoutput.path) output directly path for theAppCacheemitted files.
Default:'appcache/' -
NETWORK:string. ReflectsAppCache'sNETWORKsection.
Default:'*' -
FALLBACK:Object. ReflectsAppCache'sFALLBACKsection. 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/blogto the domain roboto when request fails.
Example 2:{ '/': '/offline-page.html' }will return contents of/offline-page.htmlfor any failed request.
Default:null -
events:boolean. Enables runtime events for AppCache. For supported events seeRuntime'sinstall()options.
Default:false -
publicPath:string. Provides a way to overrideAppCache's folder location on the server. Should be exact path to the generatedAppCachefolder.
Default:null
Example:'my/new/path/appcache' -
disableInstall:boolean. Disable the automatic installation of theAppCachewhen calling toruntime.install(). Useful when you to specify<html manifest="...">attribute manually (to cache every page user visits).
Default:false -
includeCrossOrigin:boolean. Outputs cross-origin URLs intoAppCache's manifest file. Cross-origin URLs aren't supported inAppCachewhen used on HTTPS.
Default:false
If you are using offline-plugin, feel free to submit a PR to add your project to this list.
Support it by giving feedback, contributing or just by 🌟 starring the project!