astro-website/openspec/specs/service-worker-performance/spec.md

Purpose

Improve repeat-visit performance and reduce network usage by using a service worker to pre-cache critical shell assets and apply safe runtime caching strategies.

Requirements

Requirement: Service Worker registration

The site SHALL register a Service Worker on supported browsers when running in production (HTTPS), scoped to the site root so it can control all site pages.

Scenario: Production registration

• WHEN a user loads any page in a production environment
• THEN the site registers a service worker at /sw.js with scope /

Scenario: Development does not register

• WHEN a user loads any page in a local development environment
• THEN the site does not register a service worker

Requirement: Pre-cache critical site shell assets

The Service Worker SHALL pre-cache a set of critical static assets required to render the site shell quickly on repeat visits.

Scenario: Pre-cache on install

• WHEN the service worker is installed
• THEN it caches the configured site shell assets in a versioned cache

Requirement: Runtime caching for media assets

The Service Worker SHALL use runtime caching for media assets (for example images) to reduce repeat network fetches, while ensuring content can refresh.

Scenario: Cache-first for images

• WHEN a user requests an image resource
• THEN the service worker serves the cached image when available, otherwise fetches from the network and stores the response in the media cache

Scenario: Enforce cache size bounds

• WHEN the number of cached media items exceeds the configured maximum
• THEN the service worker evicts older entries to stay within the bound

Requirement: Navigation requests avoid indefinite staleness

The Service Worker MUST NOT serve stale HTML indefinitely for navigation requests.

Scenario: Network-first navigation

• WHEN a user navigates to a page route (a document navigation request)
• THEN the service worker attempts to fetch from the network first and falls back to a cached response if the network is unavailable

Requirement: Safe updates and cache cleanup

The Service Worker SHALL use versioned caches and remove old caches during activation to ensure updated assets are used after a new deploy.

Scenario: Activate new version and clean old caches

• WHEN a new service worker version activates
• THEN it deletes caches from older versions and begins using the current versioned caches