Fix service workers

Dockerfile

@@ -2,6 +2,9 @@ FROM node:24-alpine AS builder
 
 WORKDIR /app/site
 
+ARG PUBLIC_ENABLE_SW=true
+ENV PUBLIC_ENABLE_SW=$PUBLIC_ENABLE_SW
+
 COPY site/package.json site/package-lock.json ./
 RUN npm ci --no-audit --no-fund
 

deploy/runbook.md

@@ -6,6 +6,9 @@ The deployment model is:
 - CI builds and publishes a Docker image containing the built static site
 - the server updates by pulling that image and restarting the service
 
+Build-time config (examples):
+- `PUBLIC_ENABLE_SW=true|false` toggles service worker registration in the generated HTML (defaults to `true` in the Docker build).
+
 ### Prerequisites
 
 - Docker + Docker Compose plugin available on the host
@@ -81,4 +84,3 @@ The pull should fail, but the current service should still be running:
 docker compose -f deploy/docker-compose.prod.yml ps
 curl -fsS http://localhost:8080/ > /dev/null
 ```
-

docker-compose.yml

@@ -4,6 +4,9 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+      args:
+        # Build-time toggle for service worker registration in the generated static HTML.
+        PUBLIC_ENABLE_SW: "true"
     ports:
       - "8080:80"
 

openspec/changes/service-workers/tasks.md

@@ -17,6 +17,6 @@
 
 ## 4. Verification
 
-- [ ] 4.1 Verify service worker registers in production build and does not register in dev
-- [ ] 4.2 Verify repeat navigation and asset loads hit cache (Chrome DevTools Application tab)
-- [ ] 4.3 Verify a new deploy triggers cache version update and old caches are removed
+- [x] 4.1 Verify service worker registers in production build and does not register in dev
+- [x] 4.2 Verify repeat navigation and asset loads hit cache (Chrome DevTools Application tab)
+- [x] 4.3 Verify a new deploy triggers cache version update and old caches are removed

site/.env.example

@@ -5,6 +5,11 @@ PUBLIC_SITE_URL=https://example.com
 PUBLIC_UMAMI_SCRIPT_URL=https://analytics.example.com/script.js
 PUBLIC_UMAMI_WEBSITE_ID=00000000-0000-0000-0000-000000000000
 
+# Service worker toggle (public, build-time). Use to enable in prod/staging.
+# - In `npm run dev`, service workers are not registered regardless.
+# - In `npm run build`/`preview`, SW is registered only if this is "true".
+PUBLIC_ENABLE_SW=true
+
 # Content ingestion configuration (used by scripts)
 YOUTUBE_CHANNEL_ID=UCxxxxxxxxxxxxxxxxxxxxxx
 YOUTUBE_API_KEY=

site/src/env.d.ts

@@ -4,6 +4,7 @@ interface ImportMetaEnv {
   readonly PUBLIC_SITE_URL?: string;
   readonly PUBLIC_UMAMI_SCRIPT_URL?: string;
   readonly PUBLIC_UMAMI_WEBSITE_ID?: string;
+  readonly PUBLIC_ENABLE_SW?: string;
 }
 
 interface ImportMeta {

site/src/layouts/BaseLayout.astro

@@ -57,8 +57,9 @@ const canonicalUrl = `${siteUrl}${canonicalPath.startsWith("/") ? canonicalPath
     }
 
     {
-      // Register SW only in production builds (Astro sets import.meta.env.PROD at build time).
-      import.meta.env.PROD ? (
+      // Register SW only in production builds (Astro sets import.meta.env.PROD at build time)
+      // and only when explicitly enabled by env.
+      import.meta.env.PROD && import.meta.env.PUBLIC_ENABLE_SW === "true" ? (
         <script is:inline>
           {`
           if ("serviceWorker" in navigator) {