docs: service worker info + decision

config/astro/service-worker-integration.ts

@@ -1,9 +1,11 @@
 import type { APIRoute, AstroIntegration } from 'astro';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as esbuild from 'esbuild';
 
-const serviceWorkerSrc = fileURLToPath(new URL('../../src/assets/service-worker.ts', import.meta.url));
-const serviceWorkerDist = fileURLToPath(new URL('../../dist/service-worker.js', import.meta.url));
+const filenamePath = (filename: string) => fileURLToPath(new URL(join('../../', filename), import.meta.url));
+const srcFilename = filenamePath('src/assets/service-worker.ts');
+const outFilename = filenamePath('dist/service-worker.js');
 
 export default function serviceWorkerIntegration(): AstroIntegration {
   return {
@@ -16,7 +18,7 @@ export default function serviceWorkerIntegration(): AstroIntegration {
       }) => {
         const isDevelopment = command === 'dev';
         if (isDevelopment) {
-          addWatchFile(serviceWorkerSrc);
+          addWatchFile(srcFilename);
           injectRoute({
             pattern: '/service-worker.js',
             entrypoint: import.meta.url,
@@ -26,8 +28,8 @@ export default function serviceWorkerIntegration(): AstroIntegration {
       'astro:build:done': async () => {
         try {
           await esbuild.build({
-            entryPoints: [serviceWorkerSrc],
-            outfile: serviceWorkerDist,
+            entryPoints: [srcFilename],
+            outfile: outFilename,
             target: ['es2020'],
             bundle: true,
             minify: true,
@@ -46,8 +48,8 @@ export default function serviceWorkerIntegration(): AstroIntegration {
 
 export const GET: APIRoute = async () => {
   const output =  await esbuild.build({
-    entryPoints: [serviceWorkerSrc],
-    outdir: serviceWorkerDist,
+    entryPoints: [srcFilename],
+    outdir: outFilename,
     target: ['es2020'],
     bundle: true,
     minify: false,
@@ -56,7 +58,7 @@ export const GET: APIRoute = async () => {
     sourcemap: false,
   });
 
-  return new Response(output.outputFiles[0].contents, {
+  return new Response('x' + output.outputFiles[0].contents, {
     status: 200,
     headers: {
       'Content-Type': 'application/javascript',

docs/assets.md

@@ -40,3 +40,9 @@ import Icon from '@components/Icon/';
   }
 </style>
 ```
+
+## Service Worker
+
+Head Start provides a fully customisable service worker in [`src/assets/service-worker.ts`](../src/assets/service-worker.ts) that's automatically bundle and served as `/service-worker.js` (in both development and production) and registered in each web page (using inline script in `src/layouts/PerfHead`). The service worker uses the low-level [Workbox modules](https://developer.chrome.com/docs/workbox/modules) for fine-grained control.
+
+For more background see [decision log on service worker](./decision-log/2025-01-11-service-worker.md).

docs/decision-log/2025-01-11-service-worker.md

@@ -0,0 +1,13 @@
+# Service Worker
+
+**Implement Service Worker using our own Astro Integration with Workbox modules for maximum control.**
+
+- Date: 2025-01-11
+- Alternatives Considered: existing integrations [`astrojs-service-worker`](https://github.com/tatethurston/astrojs-service-worker) and [`zastro-service-worker`](https://github.com/zachhandley/astro-service-worker)
+- Decision Made By: [Declan](https://github.com/decrek), [Jurgen](https://github.com/jurgenbelien), [Jasper](https://github.com/jbmoelker)
+
+## Decision
+
+Known existing Astro integrations for Service Workers are [`astrojs-service-worker`](https://github.com/tatethurston/astrojs-service-worker) and [`zastro-service-worker`](https://github.com/zachhandley/astro-service-worker). These integrations both use [`generateSW` from `workbox-build`](https://developer.chrome.com/docs/workbox/modules/workbox-build#generatesw), which only allows modifying the service worker through configuration.
+
+To give developers using Head Start more control over their service worker we've decided add our own [Astro Integration](../../config/astro/service-worker-integration.ts) which uses an actual file as a source ([`assets/service-worker.ts`](../../src/assets/service-worker.ts)) which developers can customise. By using low-level [Workbox modules](https://developer.chrome.com/docs/workbox/modules) this control is extended further.