posva / offline-plugin

Offline plugin (ServiceWorker, AppCache) for webpack (http://webpack.github.io/)

offline-plugin for webpack

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.

Install

npm install offline-plugin [--save-dev]

Setup

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();

Docs

• Caches
• Update process

Options

All options are optional and offline-plugin could be used without specifying them. Also see full list of default options here.

caches: 'all' | Object

Tells to the plugin 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 publicPath for webpack options, only difference is that absolute paths are not allowed

Example:
Correct value: /project/
Incorrect value: 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>.

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: Array<string | globs_pattern>

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

relativePaths: boolean

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: string | (plugin: OfflinePlugin) => void

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 argument
• string 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

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 file which will be used as ServiceWorker entry. Useful to implement additional function or handle other SW events.
  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 being returned from the caches when requested navigation URL isn't available. Similar to AppCache.FALLBACK option.
  Example: navigateFallbackURL: '/'

• events: boolean. Enables runtime events for 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 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.

• 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

Runtime

Besides plugin configuration, you also need to initialize it at runtime phase. It's done this way:

require('offline-plugin/runtime').install();

Methods

Runtime has following methods:

install(options: Object)

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).

applyUpdate()

Used to apply update for existing installation. See install options below.

install Options

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.

onInstalled

Event called exactly once when ServiceWorker or AppCache is installed. Can be useful to display "App is ready for offline usage" message.

onUpdating

Not supported for AppCache

Event called when update is found and browsers started updating process. At this moment, some assets are downloading.

onUpdateReady

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.

onUpdateFailed

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.

onUpdated

Event called when update is applied, either by calling runtime.applyUpdate() or some other way by a browser itself.

Projects using offline-plugin

• React Boilerplate (source)
• Offline Kanban (source)
• Angular CLI (source)
• Phenomic (source)

If you are using offline-plugin, feel free to submit a PR to add your project to this list.

FAQ

FAQ

License

MIT

CHANGELOG

CHANGELOG