diff --git a/README.md b/README.md index deb155a..bf7f753 100644 --- 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.