This plugin is intended to provide 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) output assets.
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, install the runtime in your client script:
require('offline-plugin/runtime').install();All options are optional and offline-plugin could be used without specifying them. Also see full list of default options here.
Tells to the plugin what to cache and how.
'all': means that everything (all the webpack output assets) 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 publicPath for webpack options, only difference is that absolute paths are not allowed
Example:
Correct value:/project/
Incorrect value:https://example.com/project
Cache update strategy. More details about updateStrategy
Default:
'changed'.
Explicitly marks the assets as external assets that you can cache. If cache asset is not one of webpack's generated assets and is not marked explicitly as external, you will receive warning about it into console. To cache external assets, add them to the caches object, by default caches: 'all' doesn't cache externals.
Default:
null
Example value:['fonts/roboto.woff']
Excludes matches assets from being added to 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 cache asset paths are generated relatively to ServiceWorker file or AppCache folder respectively.
publicPath option is ignored when this is set to true.
Default:
true
Version of the cache. Might be a function, useful in watch-mode when you need to apply dynamic value.
Functionis called with plugin instance as first argumentstringcan 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
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 file which will be used asServiceWorkerentry. Useful to implement additional function or handle other SW events.
Default: empty filescope:string. Reflects ServiceWorker.register'sscopeoption.
Default:nullnavigateFallbackURL:string. The URL being returned from the caches when requested navigation URL isn't available. Similar toAppCache.FALLBACKoption.
Example:navigateFallbackURL: '/'events:boolean. Enables runtime events for ServiceWorker. For supported events seeRuntime'sinstall()options. Default:false.
Settings for the AppCache cache. Use null or false to disable AppCache generation.
NETWORK:string. ReflectsAppCache'sNETWORKsection.
Default:'*'.directory:string. Relative (from the webpack's configoutput.path) output directly path for theAppCacheemitted files.
Default:'appcache/'.events:boolean. Enables runtime events for AppCache. For supported events seeRuntime'sinstall()options.
Default:false.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.
Besides plugin configuration, you also need to initialize it at runtime phase. It's done this way:
require('offline-plugin/runtime').install();Runtime has following methods:
Starts installation flow for ServiceWorker/AppCache it's safe and must be called each time your page loads (i.e. do not wrap it into any conditions).
Used to apply update for existing installation. See install options below.
Runtime install accepts 1 optional argument, options object. Right now you can use following runtime options:
Note: Events must be explicitly enabled for each tool (ServiceWorker/AppCache) in their options.
Event called exactly once when ServiceWorker or AppCache is installed. Can be useful to display "App is ready for offline usage" message.
Not supported for AppCache
Event called when update is found and browsers started updating process. At this moment, some assets are downloading.
Event called when onUpdating phase finished. All required assets are downloaded at this moment and are ready to be updated. Call runtime.applyUpdate() to apply update.
Event called when upUpdating phase failed by some reason. Nothing is downloaded at this moment and current update process in your code should be canceled or ignored.
Event called when update is applied, either by calling runtime.applyUpdate() or some other way by a browser itself.
Is it possible to minify ServiceWorker script output?
Yes, offline-plugin perfectly works with official webpack.optimize.UglifyJsPlugin, so if it's used your will get minified ServiceWorker script as well (no additional options required).
Is there a way to match assets with dynamic file names, like compilation hash or version?
Yes, it's possible with pattern matching, which is performed by minimatch library.
Example: main: ['index.html', 'scripts/main.*.js'].
- Added
ServiceWorker.navigateFallbackURLoption (see #71) - Added warning about development mode in
runtime.jswhen used withoutOfflinePlugininwebpack.config.js(see #74)
- Fixed absolute URLs being prefixed with relative path when
relativePaths: trueis used (#39, #60) - Added
scopeoption to ServiceWorker (#19). See ServiceWorker.register docs.
- All assets are now requested cache-bust query parameter (
__uncache=${ Date.now() }) - Assets matching in caches now ignores search (query) path of URLs
- Rename
scopeoption topublicPath(scopeis deprecated now and will produce warnings upon use) - Make
publicPath: ''(empty string) by default - Make
relativePaths: trueby default - Cache sections
'additional'and'optional'are now allowed only whenupdateStrategyoption is set to'changed' changedis now defaultupdateStrategyandhashstrategy is gone.offline-pluginnow uses webpack's build hashes to applychangeupdate strategy even when generate file names are the same. Issue 6. More details about change in docs.- Any of
updateStrategyis now usingversionoption for its version tag versionnow is not set by default and returns (when not set, e.g. default) compilation hash forupdateStrategy: 'changed'andversionforupdateStrategy: 'all'versionnow has interpolation value, use[hash]to insert compilation hash to your version stringinstall()method signature now isinstall(options)(callbacks are removed)- Runtime events are not implemented for ServiceWorker (and some for AppCache):
onUpdating,onUpdateReady,onUpdated,onInstalled.
Example:runtime.install({ onInstalled: () => ... }) - Added
applyUpdate()method to runtime - Absolute URLs can now be specified in
cachesas any other assets (they are required to be marked asexternals) - Added basic test and Travis CI
More info in CHANGELOG