Skip to content

Latest commit

 

History

History
227 lines (147 loc) · 10.8 KB

README_TEST.md

File metadata and controls

227 lines (147 loc) · 10.8 KB
Raw
offline-plugin logo

offline-plugin for webpack

npm npm Join the chat at https://gitter.im/NekR/offline-plugin

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)

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

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

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
Logo

CHANGELOG

CHANGELOG