or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdplugin-configuration.mdruntime-api.md
tile.json

tessl/npm-offline-plugin

A webpack plugin for offline-first web applications using ServiceWorker and AppCache

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/offline-plugin@5.0.x

To install, run

npx @tessl/cli install tessl/npm-offline-plugin@5.0.0

index.mddocs/

Offline Plugin

Offline Plugin is a webpack plugin that provides offline-first capabilities for webpack-based web applications. It automatically generates ServiceWorker and AppCache (as fallback) configurations to enable applications to work reliably without internet connectivity by intelligently caching webpack output assets.

Package Information

  • Package Name: offline-plugin
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install offline-plugin --save-dev

Core Imports

Plugin (for webpack configuration):

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

Runtime (for client-side code):

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

ES6/TypeScript:

import * as OfflinePluginRuntime from 'offline-plugin/runtime';
OfflinePluginRuntime.install();

Access default options:

const OfflinePlugin = require('offline-plugin');
console.log(OfflinePlugin.defaultOptions); // View default configuration

Basic Usage

1. Add to webpack configuration

// webpack.config.js
const OfflinePlugin = require('offline-plugin');

module.exports = {
  // ... your webpack config
  plugins: [
    // ... other plugins
    // OfflinePlugin should be the last plugin
    new OfflinePlugin()
  ]
};

2. Initialize in client code

// In your main entry file
require('offline-plugin/runtime').install();

With update handling:

require('offline-plugin/runtime').install({
  onUpdateReady: () => {
    console.log('SW Event:', 'onUpdateReady');
    // Update available, apply it
    require('offline-plugin/runtime').applyUpdate();
  },
  onUpdated: () => {
    console.log('SW Event:', 'onUpdated');
    // App updated, reload page
    window.location.reload();
  }
});

Architecture

Offline Plugin operates at two levels:

  • Build-time Integration: The main OfflinePlugin class hooks into webpack's compilation process to analyze assets, generate cache manifests, and create optimized ServiceWorker and AppCache configurations
  • Runtime Management: The runtime API provides client-side functions to install, update, and manage the offline functionality
  • Caching Strategy: Configurable caching policies (cache-first, network-first) with intelligent asset categorization
  • Update Mechanism: Automatic detection and application of cache updates with configurable strategies

Capabilities

Plugin Configuration

Complete webpack plugin configuration with extensive options for caching strategies, asset management, and offline behavior customization.

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

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;
  appShell?: string;
  cacheMaps?: CacheMap[];
  ServiceWorker?: ServiceWorkerOptions;
  AppCache?: AppCacheOptions | false;
}

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

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

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

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

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

Plugin Configuration

Runtime API

Client-side API for managing offline functionality, handling updates, and responding to connectivity changes.

function install(options?: InstallOptions): void;
function applyUpdate(): void;  
function update(): void;

interface InstallOptions {
  onInstalled?: () => void;
  onUpdating?: () => void;
  onUpdateReady?: () => void;
  onUpdateFailed?: () => void;
  onUpdated?: () => void;
}

Runtime API

Cache Management

Advanced caching configuration allowing fine-grained control over which assets are cached, how they're organized, and when they're updated.

Key cache features:

  • Asset categorization: Main, additional, and optional cache sections
  • Pattern matching: Glob patterns and regex support for asset selection
  • External resources: Cache external URLs and third-party assets
  • Cache maps: URL rewriting and request routing rules
  • Selective updates: Choose which assets trigger cache invalidation

ServiceWorker Integration

Automatic ServiceWorker generation with advanced features:

  • Navigation preload: Faster page loads with background requests
  • Custom scopes: Control ServiceWorker registration scope
  • Request strategies: Configurable cache-first or network-first approaches
  • Asset prefetching: Background downloading of updated resources

AppCache Fallback

Legacy AppCache support for older browsers:

  • Automatic manifest generation: Creates AppCache manifest from webpack assets
  • Fallback configuration: Specify offline fallback pages
  • Network allowlist: Control which requests bypass the cache

Constants and Special Values

// Special cache keywords (used in cache configuration arrays)
const CACHE_KEYWORDS = {
  REST: ':rest:',           // Include all remaining uncategorized assets
  EXTERNALS: ':externals:'  // Include all external URLs
};

// Auto-update default interval
const DEFAULT_AUTO_UPDATE_INTERVAL = 3600000; // 1 hour in milliseconds

// Valid update strategies
const UPDATE_STRATEGIES = ['changed', 'all'];

// Valid response strategies  
const RESPONSE_STRATEGIES = ['cache-first', 'network-first'];

// Valid updateViaCache values
const UPDATE_VIA_CACHE_OPTIONS = ['imports', 'all', 'none'];