65 lines
3.3 KiB
Markdown
65 lines
3.3 KiB
Markdown
## 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
|
|
|
|
### 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
|