chore: update README.md

birchill · Jul 13, 2024 · f95f0f8 · f95f0f8
1 parent d53829c
commit f95f0f8
Showing 1 changed file with 119 additions and 74 deletions.
diff --git a/README.md b/README.md
@@ -7,89 +7,101 @@ This is a fork of the `InjectManifest` part of the
 [`workbox-webpack-plugin`](https://github.com/GoogleChrome/workbox/) package
 but adapted to rspack's native Service Worker support.
 
-## Usage
+- [Installation](#installation)
+- [Usage](#usage)
+- [Options](#options)
+- [Differences to Workbox](#differences-to-workbox)
+- [Related projects](#related-projects)
 
-The first step is to define your service worker in a way that rspack will detect
-it.
-That means passing a `URL` object to `navigator.serviceWorker.register()`.
-For example:
-
-```js
-const registrationPromise = navigator.serviceWorker.register(
-  new URL(
-    /* webpackChunkName: "serviceworker" */
-    './sw.ts',
-    import.meta.url
-  )
-);
-```
+## Installation
 
-Note that there are various limitations to rspack's handling of URL arguments
-such as not being able to pass a URL variable.
-See rspack's [usage notes for Web
-Workers](https://www.rspack.dev/guide/features/web-workers#usage).
-
-The next step is ensuring that your generated service worker asset has a fixed
-name (e.g. `serviceworker.js`) rather than a name with a cache-busting hash in
-it.
-
-```js
-// rspack.config.js
-const config = {
-  // ...
-  output: {
-    chunkFilename: (assetInfo) => {
-      // The service worker entrypoint needs to be fixed (i.e. not have a hash
-      // appended).
-      if (assetInfo.chunk?.name === 'serviceworker') {
-        return '[name].js';
-      }
-      return '[name].[contenthash].js';
-    },
-  },
-};
 ```
-
-Finally, add the plugin to your rspack configuration.
-
-The only required parameter is `swDest`, which is the path to the _generated_
-service worker asset.
-This is _not_ necessarily the same as the path of the source file.
-
-For example, if your service worker source file is `src/sw.ts` but you
-registered it as follows:
-
-```js
-navigator.serviceWorker.register(
-  new URL(
-    /* webpackChunkName: "serviceworker" */
-    './sw.ts',
-    import.meta.url
-  )
-);
+npm install -D @birchill/inject-manifest-plugin
 ```
 
-`swDest` should be `'serviceworker.js'`, _NOT_ `src/sw.ts`.
-
-For example:
-
-```js
-// rspack.config.js
-import { InjectManifest } from '@birchill/inject-manifest-plugin';
+## Usage
 
-const config = {
-  // ...
-  plugins: [
-    new InjectManifest({
-      swDest: 'serviceworker.js',
-    }),
-  ],
-};
-```
+1. The first step is to define your service worker in a way that rspack will
+   detect it.
+   That means passing a `URL` object to `navigator.serviceWorker.register()`.
+   For example:
+
+   ```js
+   const registrationPromise = navigator.serviceWorker.register(
+     new URL(
+       /* webpackChunkName: "serviceworker" */
+       './sw.ts',
+       import.meta.url
+     )
+   );
+   ```
+
+   Note that there are various limitations to rspack's handling of URL arguments
+   such as not being able to pass a URL variable.
+   See rspack's [usage notes for Web
+   Workers](https://www.rspack.dev/guide/features/web-workers#usage).
+
+2. The next step is ensuring that your generated service worker asset has a
+   fixed name (e.g. `serviceworker.js`) rather than a name with a cache-busting
+   hash in it.
+
+   ```js
+   // rspack.config.js
+   const config = {
+     // ...
+     output: {
+       chunkFilename: (assetInfo) => {
+         // The service worker entrypoint needs to be fixed (i.e. not have a hash
+         // appended).
+         if (assetInfo.chunk?.name === 'serviceworker') {
+           return '[name].js';
+         }
+         return '[name].[contenthash].js';
+       },
+     },
+   };
+   ```
+
+3. Finally, add the plugin to your rspack configuration.
+
+   The only required parameter is `swDest`, which is the path to the _generated_
+   service worker asset.
+   This is _not_ necessarily the same as the path of the source file.
+
+   For example, if your service worker source file is `src/sw.ts` but you
+   registered it as follows:
+
+   ```js
+   navigator.serviceWorker.register(
+     new URL(
+       /* webpackChunkName: "serviceworker" */
+       './sw.ts',
+       import.meta.url
+     )
+   );
+   ```
+
+   `swDest` should be `'serviceworker.js'`, _NOT_ `src/sw.ts`.
+
+   For example:
+
+   ```js
+   // rspack.config.js
+   import { InjectManifest } from '@birchill/inject-manifest-plugin';
+
+   const config = {
+     // ...
+     plugins: [
+       new InjectManifest({
+         swDest: 'serviceworker.js',
+       }),
+     ],
+   };
+   ```
 
 ### Options
 
-The options are the same as the `InjectManifest` options in the workbox plugin
+The options are the same as the `InjectManifest` options in the Workbox plugin
 which are [documented
 here](https://developer.chrome.com/docs/workbox/modules/workbox-build#type-WebpackInjectManifestOptions).
 
@@ -214,3 +226,36 @@ here](https://developer.chrome.com/docs/workbox/modules/workbox-build#type-Webpa
 
   Note that this is name of the file generated by rspack, not the original
   service worker file.
+
+## Differences to Workbox
+
+Since this plugin relies on rspack's native handling of service workers,
+it does not support any of the features related to compiling service workers in
+Workbox.
+
+Specifically the following options are not supported:
+
+- `compileSrc`
+- `importScriptsViaChunks`
+- `mode`
+- `swSrc`
+- `webpackCompilationPlugins`
+
+Furthermore, `swDest` is a required option in this plugin as we need to know
+which asset to inject the manifest into (and which assets to automatically
+exclude from the manifest).
+
+## Related projects
+
+The following projects all recreate Workbox's `InjectManifest` functionality in
+some form.
+At the time of writing, however, I couldn't get any of them to behave correctly
+with rspack's native service worker generation.
+
+- [workbox-rspack-plugin](https://www.npmjs.com/package/workbox-rspack-plugin).
+  Port of Workbox to rspack.
+- [@aaron/workbox-rspack-plugin](https://www.npmjs.com/package/@aaroon/workbox-rspack-plugin).
+  More up-to-date port.
+- [`inject-manifest-plugin`](https://www.npmjs.com/package/inject-manifest-plugin).
+  A much leaner version of what workbox does, adapter to work with both webpack
+  and rspack.