Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OfflinePlugin
✓ import OfflinePlugin from 'offline-plugin'
✗ const OfflinePlugin = require('offline-plugin').default
Default import works in both ESM and CJS. Do not use .default with require.
OfflinePlugin (require)
✓ const OfflinePlugin = require('offline-plugin')
✗ const { OfflinePlugin } = require('offline-plugin')
CJS require returns the constructor directly; no destructuring needed.
Runtime (in browser)
✓ import * as OfflinePluginRuntime from 'offline-plugin/runtime'
✗ import OfflinePluginRuntime from 'offline-plugin/runtime'
The runtime module is a namespace object, so use import * as. Alternatively use require('offline-plugin/runtime') in CJS.
AppCache
✓ import OfflinePlugin from 'offline-plugin';
new OfflinePlugin({ AppCache: true })
✗ import { AppCache } from 'offline-plugin'
AppCache is an option, not a separate export.
Configures OfflinePlugin in webpack and installs the runtime to activate ServiceWorker caching.
// webpack.config.js
import OfflinePlugin from 'offline-plugin';
export default {
plugins: [
new OfflinePlugin({
appShell: '/index.html',
caches: {
main: ['app.*.js', 'vendor.*.js', 'styles.*.css'],
additional: ['*.png', '*.svg', '*.jpg'],
optional: [':rest:']
},
ServiceWorker: {
events: true,
navigateFallbackURL: '/'
},
AppCache: false
})
]
};
// client.js (e.g. entry point)
import * as OfflinePluginRuntime from 'offline-plugin/runtime';
OfflinePluginRuntime.install();
Errors
Common errors & fixes
Error: OfflinePlugin is not a constructor
Improper import style: using require('offline-plugin').default or destructuring.
fixUse const OfflinePlugin = require('offline-plugin') (CJS) or import OfflinePlugin from 'offline-plugin' (ESM). Cannot find module 'offline-plugin/runtime'
Missing runtime file or incorrect import path.
fixInstall offline-plugin as a dependency (not devDependency) and use import * as OfflinePluginRuntime from 'offline-plugin/runtime'.
ServiceWorker registration failed: InvalidStateError
ServiceWorker script URL is not served with correct MIME type or is blocked by CSP.
fixEnsure the service worker file is served with text/javascript MIME type and CSP allows worker-src.
Audit
Dependencies
webpackrequiredPeer dependency when using as webpack plugin; supported versions 2+ (dropped webpack 1 in v5.0.0).