Plugin Configuration

The OfflinePlugin class provides extensive configuration options for customizing offline behavior, caching strategies, and asset management.

Plugin Constructor

class OfflinePlugin {
  constructor(options?: PluginOptions);
  apply(compiler: webpack.Compiler): void;
  static defaultOptions: PluginOptions;
}

Create a new OfflinePlugin instance with optional configuration.

Import:

const OfflinePlugin = require('offline-plugin');

Parameters:

• options (optional): Configuration object with plugin settings

Core Configuration Options

Basic Options

interface PluginOptions {
  caches?: 'all' | CacheConfiguration;
  publicPath?: string;
  updateStrategy?: 'changed' | 'all';
  responseStrategy?: 'cache-first' | 'network-first';
  externals?: string[];
  excludes?: string[];
  relativePaths?: boolean;
  version?: string | Function;
  autoUpdate?: boolean | number;
  rewrites?: Function | Object;
  safeToUseOptionalCaches?: boolean;
}

caches (default: 'all') Defines which assets to cache. Set to 'all' to cache all webpack output assets, or provide detailed cache configuration.

publicPath (default: webpack's output.publicPath) The base URL for all cached assets. Override webpack's publicPath setting.

updateStrategy (default: 'changed')

• 'changed': Only update when assets change
• 'all': Update all assets when any asset changes

responseStrategy (default: 'cache-first')

• 'cache-first': Check cache first, fallback to network
• 'network-first': Try network first, fallback to cache

externals (default: []) Array of external URLs to cache alongside webpack assets.

externals: [
  '/static/img/logo.png',
  'https://fonts.googleapis.com/css?family=Roboto'
]

excludes (default: ['**/.*', '**/*.map', '**/*.gz']) Glob patterns for assets to exclude from caching.

relativePaths (default: auto-detected) Generate relative paths in cache manifest instead of absolute URLs.

version (default: current timestamp) Cache version identifier. Can be string or function returning string.

autoUpdate (default: false) Enable automatic update checking. Set to true for 1-hour interval, or number for custom milliseconds.

rewrites (default: function that handles index.html rewriting) Function or object for rewriting asset paths in the cache manifest. Useful for handling SPA routing.

safeToUseOptionalCaches (default: false)
Set to true to suppress warnings when using additional and optional cache sections. Only enable if assets have unique names with hashes.

Advanced Cache Configuration

interface CacheConfiguration {
  main?: string[];
  additional?: string[];
  optional?: string[];
}

main - Essential assets loaded on first visit additional - Assets cached but not required for basic functionality
optional - Assets cached opportunistically

Special cache keys:

• ':rest:' - Include all remaining uncategorized assets
• ':externals:' - Include all external URLs

caches: {
  main: ['index.html', 'main.js', 'main.css'],
  additional: [':rest:'],
  optional: [':externals:']
}

App Shell Configuration

interface PluginOptions {
  appShell?: string;
  cacheMaps?: CacheMap[];
}

interface CacheMap {
  match: string | Function;
  to?: string | Function;
  requestTypes?: ('navigate' | 'same-origin' | 'cross-origin')[];
}

appShell HTML file to return for all navigation requests (Single Page Application pattern).

cacheMaps URL rewriting rules for request routing.

appShell: '/app-shell.html',
cacheMaps: [
  {
    match: /^\/api\/.*$/,
    to: '/offline-api-fallback.json',
    requestTypes: ['same-origin']
  }
]

ServiceWorker Configuration

interface ServiceWorkerOptions {
  output?: string;
  entry?: string;
  scope?: string;
  events?: boolean;
  minify?: boolean;
  forceInstall?: boolean;
  updateViaCache?: 'imports' | 'all' | 'none';
  prefetchRequest?: PrefetchRequestOptions;
  navigationPreload?: boolean | 'auto';
}

interface PrefetchRequestOptions {
  credentials?: 'same-origin' | 'include' | 'omit';
  headers?: { [key: string]: string };
  mode?: 'cors' | 'no-cors' | 'same-origin';
  cache?: string;
}

output (default: 'sw.js') ServiceWorker file name.

entry (default: webpack generated entry) Entry point file for the ServiceWorker. Used to customize ServiceWorker logic.

scope (default: same as publicPath) ServiceWorker registration scope.

events (default: false) Enable runtime event callbacks.

minify (default: based on webpack mode) Enable/disable ServiceWorker code minification. Can be boolean or minification options object.

forceInstall (default: false) Force ServiceWorker installation even on insecure origins (not recommended for production).

updateViaCache (default: 'imports') Controls how the browser's HTTP cache is used when checking for ServiceWorker updates:

• 'imports': Check cache for imported scripts only
• 'all': Check cache for ServiceWorker and all imported scripts
• 'none': Bypass cache for all ServiceWorker-related requests

navigationPreload (default: 'auto') Enable navigation preload for faster page loads.

prefetchRequest Default options for prefetch requests.

ServiceWorker: {
  output: 'service-worker.js',
  scope: '/app/',
  events: true,
  navigationPreload: true,
  prefetchRequest: {
    credentials: 'same-origin',
    mode: 'cors'
  }
}

AppCache Configuration

interface AppCacheOptions {
  directory?: string;
  NETWORK?: string;
  FALLBACK?: { [path: string]: string };
  caches?: string[];
  events?: boolean;
  disableInstall?: boolean;
  includeCrossOrigin?: boolean;
}

NETWORK (default: '*') Network allowlist entries.

FALLBACK Fallback mappings for offline pages.

directory (default: 'appcache/') Output directory for AppCache manifest.

AppCache: {
  directory: 'cache/',
  NETWORK: '*',
  FALLBACK: {
    '/': '/offline.html'
  },
  events: true
}

Static Properties

class OfflinePlugin {
  static defaultOptions: PluginOptions;
}

Access default configuration values for reference or extension.

Usage Examples

Basic Configuration

new OfflinePlugin({
  responseStrategy: 'network-first',
  externals: ['/favicon.ico']
})

Advanced Configuration

new OfflinePlugin({
  caches: {
    main: ['index.html', 'main.js'],
    additional: ['**/*.css'],
    optional: [':externals:']
  },
  updateStrategy: 'changed',
  appShell: '/shell.html',
  ServiceWorker: {
    events: true,
    navigationPreload: true
  },
  autoUpdate: 1000 * 60 * 30 // 30 minutes
})

Development Configuration

new OfflinePlugin({
  excludes: ['**/*.map', '**/*.hot-update.*'],
  relativePaths: true,
  ServiceWorker: {
    minify: false
  }
})