53 lines
3.0 KiB
Markdown
53 lines
3.0 KiB
Markdown
## 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.
|
|
|