inject-manifest-plugin

Injects a Workbox PWA manifest into a Service Worker. Alternative for the InjectManifest plugin in the workbox-webpack-plugin.

• Supports webpack and Rspack
• Compatible with Google Workbox
• Check out the demo or the papua PWA template
  • Get started by running npm init now papua ./my-pwa pwa
• Replaces self.INJECT_MANIFEST_PLUGIN variable in a service-worker.[jt]s file with a { url: string; revision: string (hash) } array.

service-worker File

To get started add a service-worker.js or service-worker.ts file to the root of the project and install the necessary dependencies with npm install url-join workbox-core workbox-expiration workbox-precaching workbox-routing workbox-strategies.

1import join from 'url-join'
2import { clientsClaim } from 'workbox-core'
3import { ExpirationPlugin } from 'workbox-expiration'
4import { precacheAndRoute, createHandlerBoundToURL } from 'workbox-precaching'
5import { registerRoute } from 'workbox-routing'
6import { StaleWhileRevalidate } from 'workbox-strategies'
7
8clientsClaim() // Allows updating open service workers.
9
10// Add types for the plugin and workbox.
11declare global {
12  interface Window {
13    INJECT_MANIFEST_PLUGIN: { url: string; revision: string }[]
14    skipWaiting: Function
15  }
16}
17
18// Add all assets generated during build to the browser cache.
19precacheAndRoute(self.INJECT_MANIFEST_PLUGIN)
20
21const fileExtensionRegexp = new RegExp('/[^/?]+\\.[^/]+$')
22registerRoute(
23  // Return false to exempt requests from being fulfilled by index.html.
24  ({ request, url }) => {
25    // If this isn't a navigation, skip.
26    if (request.mode !== 'navigate') {
27      return false
28    } // If this is a URL that starts with /_, skip.
29
30    if (url.pathname.startsWith('/_')) {
31      return false
32    } // If this looks like a URL for a resource, because it contains // a file extension, skip.
33
34    if (url.pathname.match(fileExtensionRegexp)) {
35      return false
36    } // Return true to signal that we want to use the handler.
37
38    return true
39  },
40  createHandlerBoundToURL(join(process.env.PUBLIC_URL as string, '/index.html'))
41)
42
43// An example runtime caching route for requests that aren't handled by the
44// precache, in this case same-origin .png requests like those from in public/
45registerRoute(
46  // Add in any other file extensions or routing criteria as needed.
47  ({ url }) => url.origin === self.location.origin && url.pathname.endsWith('.png'), // Customize this strategy as needed, e.g., by changing to CacheFirst.
48  new StaleWhileRevalidate({
49    cacheName: 'images',
50    plugins: [
51      // Ensure that once this runtime cache reaches a maximum size the
52      // least-recently used images are removed.
53      new ExpirationPlugin({ maxEntries: 50 }),
54    ],
55  })
56)
57
58// Update cached assets after reload without the need for the user to close all open tabs.
59self.addEventListener('message', (event) => {
60  if (event.data && event.data.type === 'SKIP_WAITING') {
61    self.skipWaiting()
62  }
63})

Service Worker Registration

The service-worker.js asset created during the build needs to be dynamically loaded and registered from any regular JavaScript entry.

1import join from 'url-join'
2
3const store = {
4  ready: false,
5  update: false,
6  error: false,
7  offline: false
8}
9
10const isLocalhost = Boolean(
11  window.location.hostname === 'localhost' ||
12    // [::1] is the IPv6 localhost address.
13    window.location.hostname === '[::1]' ||
14    // 127.0.0.0/8 are considered localhost for IPv4.
15    window.location.hostname.match(/^127(?:\.(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}$/)
16)
17
18function registerValidSW(swUrl: string) {
19  navigator.serviceWorker
20    .register(swUrl)
21    .then((registration) => {
22      store.ready = true
23      registration.onupdatefound = () => {
24        const installingWorker = registration.installing
25        if (installingWorker == null) {
26          return
27        }
28        installingWorker.onstatechange = () => {
29          if (installingWorker.state === 'installed') {
30            if (navigator.serviceWorker.controller) {
31              // Force contents to update on reload.
32              if (registration && registration.waiting) {
33                registration.waiting.postMessage({ type: 'SKIP_WAITING' })
34              }
35              // Timeout to ensure message passed.
36              setTimeout(() => { store.update = true }, 100)
37            }
38          }
39        }
40      }
41    })
42    .catch(() => { error = true })
43}
44
45function checkValidServiceWorker(swUrl: string) {
46  fetch(swUrl, {
47    headers: { 'Service-Worker': 'script' },
48  })
49    .then((response) => {
50      const contentType = response.headers.get('content-type')
51      if (
52        response.status === 404 ||
53        (contentType != null && contentType.indexOf('javascript') === -1)
54      ) {
55        navigator.serviceWorker.ready.then((registration) => {
56          registration.unregister().then(() => {
57            window.location.reload()
58          })
59        })
60      } else {
61        registerValidSW(swUrl)
62      }
63    })
64    .catch(() => { store.offline = true })
65}
66
67export function register() {
68  if (process.env.NODE_ENV === 'production' && 'serviceWorker' in navigator) {
69    const publicUrl = new URL(process.env.PUBLIC_URL, window.location.href)
70    if (publicUrl.origin !== window.location.origin) {
71      store.error = true
72      return
73    }
74
75    window.addEventListener('load', () => {
76      const swUrl = join(process.env.PUBLIC_URL, '/service-worker.js')
77
78      if (isLocalhost) {
79        checkValidServiceWorker(swUrl)
80        navigator.serviceWorker.ready.then(() => Todo.setReady())
81      } else {
82        registerValidSW(swUrl)
83      }
84    })
85  }
86}
87
88// Useful if you had a worker registered in the past on this url.
89export function unregister() {
90  if ('serviceWorker' in navigator) {
91    navigator.serviceWorker.ready
92      .then((registration) => {
93        registration.unregister()
94      })
95      .catch((error) => { store.error = error.message })
96  }
97}

Call the register() method from anywhere:

1import { register } from './registration'
2
3createRoot(document.body).render(<p>my App!</p>)
4
5register()

Plugin Usage in webpack.config.mjs / rspack.config.mjs

When used in a project with webpack-cli or @rspack/cli make sure that the package.json contains "type": "module" or the configuration file ends with .mjs. Both the plugin as well as the registration require the process.env.PUBLIC_URL variable to be set.

1import { InjectManifestPlugin } from 'inject-manifest-plugin'
2
3export default {
4  plugins: [new InjectManifestPlugin()],
5}

Configuration

1new InjectManifestPlugin({
2  file: 'my-worker.js', // Default: service-worker.js
3  injectionPoint: 'global.replace-this', // Default: self.INJECT_MANIFEST_PLUGIN
4  exclude: ['extension/*'], // Default: []
5  removeHash: true, // Default: false
6  chunkFilename: 'worker': // Default: service-worker
7})

file should point to a Service Worker file in the project and will automatically be added as an entry. The Service Worker entry chunk will be called service-worker. The injectionPoint can be any text that will be replaced in the Service Worker code with the generated manifest. Using the exclude array it's possible to keep some assets from appearing in the manifest to avoid caching in the Service Worker. The array can include globs and items are matched against the generated assets using minimatch. With the removeHash option it's possible to ensure the name of the generated Service Worker asset matches the input file. A Service Worker cannot change it's name once registered, therefore it's important that no hash is added. Since, this option uses a workaround, it's generally recommended to avoid hashing any JavaScript assets as the Service Worker will usually ensure well enough that all assets are up-to-date. The chunkFilename names the injected Service Worker chunk.

Programmatic Usage

1import webpack from 'webpack'
2import HtmlWebpackPlugin from 'html-webpack-plugin'
3import { InjectManifestPlugin } from 'inject-manifest-plugin'
4
5const configuration: webpack.Configuration = {
6  plugins: [
7    new InjectManifestPlugin(),
8    new HtmlWebpackPlugin()
9  ],
10}
11
12// When using programmatic API, otherwise place configuration in webpack.config.js.
13webpack(configuration, (error, stats) => { ... })

1import { Configuration, rspack } from '@rspack/core'
2import { InjectManifestPlugin } from 'inject-manifest-plugin'
3
4const configuration: Configuration = {
5  builtins: {
6    html: [{}], // Empty object creates a default html template (index.html).
7  },
8  plugins: [new InjectManifestPlugin()],
9}
10
11// When using programmatic API, otherwise place configuration in rspack.config.js.
12rspack(configuration, (error, stats) => { ... })