feature: Service worker (custom Astro integration)

astro.config.ts

@@ -5,6 +5,7 @@ import sitemap from '@astrojs/sitemap';
 import type { PluginOption } from 'vite';
 import { isPreview } from './config/preview';
 import pkg from './package.json';
+import serviceWorker from './config/astro/service-worker-integration.ts';
 
 const productionUrl = `https://${ pkg.name }.pages.dev`; // overwrite if you have a custom domain
 const localhostPort = 4323; // 4323 is "head" in T9
@@ -50,7 +51,10 @@ export default defineConfig({
     // @see https://docs.astro.build/en/guides/images/#configure-no-op-passthrough-service
     service: passthroughImageService()
   },
-  integrations: [sitemap()],
+  integrations: [
+    sitemap(),
+    serviceWorker()
+  ],
   output: isPreview ? 'server' : 'static',
   server: { port: localhostPort },
   site: siteUrl,

config/astro/service-worker-integration.ts

@@ -0,0 +1,67 @@
+import type { APIRoute, AstroIntegration } from 'astro';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as esbuild from 'esbuild';
+
+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 {
+    name: 'service-worker',
+    hooks: {
+      'astro:config:setup': async ({
+        command,
+        injectRoute,
+        addWatchFile,
+      }) => {
+        const isDevelopment = command === 'dev';
+        if (isDevelopment) {
+          addWatchFile(srcFilename);
+          injectRoute({
+            pattern: '/service-worker.js',
+            entrypoint: import.meta.url,
+          });
+        }
+      },
+      'astro:build:done': async () => {
+        try {
+          await esbuild.build({
+            entryPoints: [srcFilename],
+            outfile: outFilename,
+            target: ['es2020'],
+            bundle: true,
+            minify: true,
+            allowOverwrite: true,
+            sourcemap: true,
+          });
+        } catch (e) {
+          console.error('Failed to build service worker');
+          console.error(e);
+          process.exit(1);
+        }
+      },
+    },
+  };
+}
+
+export const GET: APIRoute = async () => {
+  const output =  await esbuild.build({
+    entryPoints: [srcFilename],
+    outdir: outFilename,
+    target: ['es2020'],
+    bundle: true,
+    minify: false,
+    write: false,
+    allowOverwrite: true,
+    sourcemap: false,
+  });
+
+  return new Response(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.