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.
Function
is called with plugin instance as first argumentstring
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
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 asServiceWorker
entry. Useful to implement additional function or handle other SW events.
Default: empty filescope
:string
. Reflects ServiceWorker.register'sscope
option.
Default:null
navigateFallbackURL
:string
. The URL being returned from the caches when requested navigation URL isn't available. Similar toAppCache.FALLBACK
option.
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
'sNETWORK
section.
Default:'*'
.directory
:string
. Relative (from the webpack's configoutput.path
) output directly path for theAppCache
emitted files.
Default:'appcache/'
.events
:boolean
. Enables runtime events for AppCache. For supported events seeRuntime
'sinstall()
options.
Default:false
.FALLBACK
:Object
. ReflectsAppCache
'sFALLBACK
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
.
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.navigateFallbackURL
option (see #71) - Added warning about development mode in
runtime.js
when used withoutOfflinePlugin
inwebpack.config.js
(see #74)
- Fixed absolute URLs being prefixed with relative path when
relativePaths: true
is used (#39, #60) - Added
scope
option 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
scope
option topublicPath
(scope
is deprecated now and will produce warnings upon use) - Make
publicPath: ''
(empty string) by default - Make
relativePaths: true
by default - Cache sections
'additional'
and'optional'
are now allowed only whenupdateStrategy
option is set to'changed'
changed
is now defaultupdateStrategy
andhash
strategy is gone.offline-plugin
now uses webpack's build hashes to applychange
update strategy even when generate file names are the same. Issue 6. More details about change in docs.- Any of
updateStrategy
is now usingversion
option for its version tag version
now is not set by default and returns (when not set, e.g. default) compilation hash forupdateStrategy: 'changed'
andversion
forupdateStrategy: 'all'
version
now 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
caches
as any other assets (they are required to be marked asexternals
) - Added basic test and Travis CI
More info in CHANGELOG