Skip to content

Latest commit

 

History

History
executable file
·
166 lines (100 loc) · 8.75 KB

options.md

File metadata and controls

executable file
·
166 lines (100 loc) · 8.75 KB
Raw

Options

All options are optional, see the defaults here.

appShell: string

Enables your application to work with the app shell model. Set to the HTML file you want to return for all navigation requests.

More information about appShell

Default: null. Example: '/app-shell.html'

responseStrategy: 'cache-first' | 'network-first'

With 'cache-first' all request are sent to consult the cache first and if the cache is empty, request is sent to the network. With 'network-first' all request are sent to the network first and if network request fails consult the cache as a fallback.

Default: 'cache-first'.

externals: Array<string>

Specify additional (external to the build process) URLs to be cached.

Default: null
Example: ['/static/img/media.png', 'https://fonts.googleapis.com/css?family=Roboto']

excludes: Array<string | globs_pattern>

Excludes assets from being cached. Note: Exclusion is performed before rewrites.

Default: ['**/.*', '**/*.map', '**/*.gz']
Excludes all files which start with . or end with .map or .gz

autoUpdate: true | number

Enable automatic updates of the ServiceWorker and AppCache. If set to true, it uses default interval of 1 hour. Set a number value to 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)

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.

This option is ignored when publicPath is set. publicPath option is ignored when this option is set explicitly to true.

Default: true

rewrites: Function | Object

Provides a way to change the URL an asset is loaded from. This is useful when assets are served differently than the client expects, e.g. if you have them on a CDN.

Read more about rewrites option and default function

Default: Rewrite /index.html to /

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 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. This option should not be changed at all after you deploy ServiceWorker to 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'

  • 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'

  • navigationPreload: boolean | Object | ':auto:'. See ServiceWorker.navigationPreload option documentation

Default: ':auto:'

  • 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: 'include' }

  • minify: boolean. If set to true or false, the ServiceWorker's output will be minified or not accordingly. If set to something else, the ServiceWorker output will be minified if you are using webpack.optimize.UglifyJsPlugin or terser-webpack-plugin in your configuration. Default: null

publicPath: string

Similar to 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 publicPath value isn't specified at all (either by this option or by webpack's output.publicPath option), relative paths are used (see relativePaths option).

Examples:
publicPath: '/project/'
publicPath: 'https://example.com/project'

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 and time
Example: 2018-6-20 09:53:56
Please note that if you use the default value (date and time), the version of service worker will change on each build of your project.

caches: 'all' | Object

Allows you to adjust what and how to cache the assets.

  • '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 | RegExp> sections (properties): main, additional, optional. All sections are optional and by default are empty (no assets added).

More information about caches

Default: 'all'.

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 runtime.install(). Useful when you want 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

updateStrategy: 'changed' | 'all'

Cache update strategy. More details about updateStrategy
Please, do not change this option unless you're sure you know what you're doing.

Default: 'changed'.