astro-website/openspec/changes/service-workers/design.md

Context

This change introduces a Service Worker to improve perceived load time and reduce network usage on repeat visits by caching critical assets in the browser.

The site is a static Astro build. That means:

• The Service Worker should live at the site root (/sw.js) so it can control all routes.
• Navigations (HTML documents) should not be cached in a way that causes indefinite staleness after new deploys.

Goals / Non-Goals

Goals:

• Improve repeat-visit performance by pre-caching the critical site shell assets.
• Add runtime caching for media assets (images) with bounded storage usage.
• Ensure safe update behavior: cache versioning and cleanup on activate.
• Keep local development predictable by not registering the Service Worker in dev by default.

Non-Goals:

• Full offline-first experience for all routes/content.
• Background sync, push notifications, or complex offline fallbacks.
• Server-side caching (handled by separate changes, if desired).

Decisions

1. Implement a lightweight, custom Service Worker (no Workbox) Rationale: The project already outputs static assets and the needed caching strategies are straightforward. A small custom /sw.js avoids adding a build-time dependency and keeps behavior explicit. Alternatives considered:

• Workbox: powerful, but adds dependency surface area and build configuration overhead.

2. Cache strategy by request type Rationale: Different resources have different freshness requirements.

• Navigations (HTML documents): Network-first, fallback to cache on failure. This minimizes stale HTML risks while still helping resiliency.
• Static shell assets (CSS/JS/fonts/icons): Pre-cache on install and serve from cache for speed.
• Images/media: Cache-first with a size bound and eviction to avoid unbounded storage.

3. Versioned caches + activation cleanup Rationale: Static sites frequently redeploy; versioning ensures updates can be picked up and old assets are not served after deploy. On activate, the SW deletes prior version caches. Implementation approach:

• Use cache names like shell-v<version> and media-v<version>.
• Update the version string on build (initially a constant; later can be automated).

4. Disable SW registration in development by default Rationale: Service worker caching can confuse local iteration and cause stale assets during development. Implementation approach:

• Register SW only when import.meta.env.PROD is true (Astro build-time flag) or an explicit runtime guard is met.

Risks / Trade-offs

• [Stale or broken assets after deploy] → Use versioned caches and delete old caches during activation. Prefer network-first for navigations.
• [Over-caching HTML causes outdated content] → Do not use cache-first for navigation; do not pre-cache HTML pages.
• [Storage growth due to images] → Enforce a max-entry limit with eviction for media cache.
• [Browser compatibility gaps] → Service worker is progressive enhancement; site must still function without it.