3.3 KiB
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.jswith 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
Requirement: Critical assets do not remain stale after deploy
The service worker and server caching strategy MUST ensure critical shell assets (including the global stylesheet and service worker script) do not remain stale across deploys.
The implementation MUST include at least one cache-busting mechanism for critical assets, such as:
- content-hashed asset filenames, or
- an asset version query suffix that changes per deploy
Scenario: New deploy updates critical CSS
- WHEN a new deploy is released and a returning user loads the site
- THEN the user receives the updated global stylesheet without requiring a manual hard refresh
Scenario: Service worker updates predictably
- WHEN a new deploy is released
- THEN the browser can retrieve the updated service worker script and activate it without being pinned by long-lived caches