# Build an Offline-Capable Progressive Web App Feature

Amo ID: AMO-P-000350
Version: 1.0.0
Public URL: https://amo.ng/prompts/build-offline-capable-progressive-web-app-feature

Summary: Implement one approved installable, offline-aware PWA feature with bounded caching, sync conflict handling, device tests, and a reversible release handoff.

Use this for: Use this to add one approved Progressive Web App feature to an existing web repository with explicit offline behavior, privacy-safe storage, update handling, failure tests, and recovery evidence.

Category: Codex & Coding
Tool: Codex
Difficulty: Expert
Prompt type: feature build

## Best Use Cases

1. Adding an approved offline-capable journey to an existing responsive web application.
2. Implementing a web app manifest, service-worker lifecycle, bounded caches, and user-visible update behavior.
3. Building an approved offline data-entry or reference feature with explicit synchronization and conflict rules.
4. Testing installability, network loss, stale assets, storage limits, updates, and safe service-worker rollback before release review.

## Prompt Body

Implement one approved, offline-capable Progressive Web App feature in the authorized existing web repository. Build only the supplied user journey and supporting installability, caching, storage, synchronization, and update behavior. Do not turn the task into a native application, a full application rewrite, or a store-submission project.

## Required inputs

Approved PWA feature specification:
{{approved_pwa_feature_specification}}

Repository and browser context:
{{repository_and_browser_context}}

Offline data and synchronization contract:
{{offline_data_and_sync_contract}}

Privacy, security, and storage boundaries:
{{privacy_security_and_storage_boundaries}}

Acceptance criteria and authorized scope:
{{acceptance_criteria_and_authorized_scope}}

## Evidence and assumption rules

1. Classify material statements as supplied fact, repository observation, execution evidence, assumption, conflict, missing information, or unresolved uncertainty. Cite files, symbols, routes, browser versions, commands, reports, and captured test artifacts where available.
2. Do not invent offline requirements, synchronization policy, conflict precedence, retention rules, storage quotas, browser support, API behavior, credentials, test results, deployment state, or approval.
3. Treat the supplied feature, data, synchronization, privacy, and storage contracts as binding. If they conflict with current repository behavior, stop the affected path and request a decision from the product owner, data owner, privacy reviewer, or engineering owner.
4. Separate code and configuration actually changed from recommendations. Separate browser checks actually run from expected behavior. Do not infer offline reliability or installability from the presence of a manifest or service-worker file.
5. Use synthetic or sanitized fixtures. Never request secrets or production personal data. Do not cache authentication responses, tokens, private pages, personal data, or confidential records unless the supplied contract expressly authorizes the exact data and protection mechanism.
6. Preserve unrelated repository and configuration work. Avoid a framework replacement or broad refactor unless the approved feature cannot be implemented safely without a separately authorized decision.

## Authorization boundaries

- Implementation requires an authorized repository, an approved feature specification, supported-browser targets, explicit offline and synchronization rules, safe test data, and authority over the identified files and commands.
- Inspect only the supplied workspace, local browser tooling, fixtures, API contracts, build configuration, and test output. Do not imply access to production devices, app stores, live push services, production APIs, analytics accounts, or deployment systems.
- Do not deploy, merge, push, submit to an application store, enable production push messages, alter production storage, register new live domains, or change DNS, hosting, analytics, or production APIs.
- Do not use a broad cache-everything rule, suppress authentication checks, retain sensitive data across logout, or make destructive storage/schema changes without explicit approval and a tested migration and recovery path.
- Stop before any action whose data exposure, browser blast radius, update behavior, cost, reversibility, or authorization is unclear. Record the blocked action and smallest safe alternative.

## Repository inspection and implementation checkpoint

1. Inspect the application entry points, routes, rendering model, asset build, existing manifest and service-worker code, cache headers, API clients, authentication and logout paths, client storage, synchronization logic, error handling, tests, monitoring, and release controls that are actually present.
2. Map the approved journey across online, intermittent, and offline states. Identify the minimum application shell, assets, data, mutations, and recovery behavior needed, plus every item that must remain network-only.
3. Establish an authorized baseline for build output, current tests, page behavior, accessibility, performance, and any existing service-worker registration. Record commands and actual observations without rewriting tests to hide failures.
4. Before editing, present a concise checkpoint with affected files, cache and storage boundaries, service-worker lifecycle, synchronization rules, browser matrix, test plan, rollout control, rollback, and blockers. Continue only within {{acceptance_criteria_and_authorized_scope}}.

## Implement the approved PWA feature

Apply the smallest coherent repository change. Where applicable:

1. Implement or update the web app manifest with approved identity, icons already available or explicitly supplied, start URL, display behavior, theme values, scope, and installability requirements. Do not fabricate branded assets.
2. Register the service worker within the approved scope. Use deterministic cache names and versions, bounded precaching, safe runtime strategies by resource class, request and response eligibility checks, and explicit cleanup of obsolete caches.
3. Keep navigation, authenticated content, APIs, user data, third-party responses, and error responses out of caches unless the contract explicitly defines a safe strategy. Respect server authorization and do not treat cached UI as authorization.
4. Implement the approved offline user journey with clear online, offline, stale, synchronizing, conflicted, failed, storage-unavailable, and recovery states. Preserve semantic HTML, keyboard operation, focus, readable status announcements, responsive layout, and motion preferences.
5. Implement only the approved client storage and mutation queue. Define record identity, validation, ordering, retry, idempotency, expiry, encryption or exclusion rules, logout cleanup, schema upgrades, and quota behavior from supplied contracts.
6. Apply the approved synchronization and conflict policy. Do not silently overwrite newer server state. Surface unresolved conflicts with sufficient evidence for the user or accountable owner to decide.
7. Implement a controlled update lifecycle so a new worker does not unexpectedly discard in-progress work. Provide an accessible update notice or another approved activation rule, plus recovery from an incompatible cached version.
8. Add privacy-safe diagnostics for worker version, cache state, offline operations, retries, conflicts, and failures without logging sensitive content. Keep production analytics or push integration disabled.

## Domain-specific verification

Use the approved browser and device matrix, local tooling, and synthetic data. Test at least:

- first visit online, subsequent offline launch, refresh while offline, and navigation to a route not previously cached;
- installability and launch scope in each supported browser where the environment permits it;
- static-asset update, waiting-worker behavior, stale cache removal, interrupted update, and rollback to the previous release;
- online-to-offline and offline-to-online transitions during reads and writes;
- queued mutation ordering, duplicate submission, retry after uncertain completion, partial synchronization, and idempotent replay;
- simultaneous or divergent edits according to the supplied conflict contract;
- expired data, revoked access, logout, user change, storage denial, quota exhaustion, corrupt local state, and storage-schema upgrade;
- API timeout, malformed response, authentication expiry, server rejection, rate limiting, and unavailable dependency;
- loading, empty, offline, stale, conflict, error, and recovery announcements with keyboard and screen-reader checks;
- responsive behavior, asset weight, cache size, startup behavior, and performance acceptance criteria under the supplied conditions.

For every check, record the browser and version, network/storage setup, fixture, build identifier, exact command or procedure, expected result, actual result, evidence, and pass, fail, blocked, or not run status. Do not claim mobile-device, accessibility, offline, security, or performance readiness for combinations that were not exercised.

## Failure, recovery, and stop conditions

- Do not replay uncertain mutations until the local operation identifier and server state have been reconciled.
- Provide a bounded recovery path for a broken worker or cache: disable the feature flag where available, unregister or supersede only the affected worker, clear only owned caches and storage after preserving recoverable work, restore the prior assets, and verify the online baseline.
- Stop with a blocked-handoff report if essential repository access, the approved feature, browser support policy, offline data rules, synchronization/conflict contract, privacy boundary, test tooling, or authority is absent or contradictory.
- Stop if implementation would cache unauthorized content, expose data across users, discard unresolved offline work, broaden service-worker scope, require an unapproved production API change, or lack a safe update and rollback route.

## Output contract

Return:

1. **Implementation status**: Applied and tested, Applied with gaps, Proposed only, or Blocked, with environment, browser coverage, data boundary, and evidence limitations.
2. **Feature-state map**: User journey step, online behavior, offline behavior, stored data, synchronization rule, error/recovery state, and acceptance criterion.
3. **Repository and configuration change manifest**: File or symbol, change, reason, applied/proposed state, cache or data effect, test evidence, and rollback treatment.
4. **Cache, storage, and synchronization contract record**: Resource or record, eligibility, lifetime, versioning, privacy rule, retry/idempotency behavior, conflict handling, and cleanup.
5. **Browser and failure test ledger**: Browser/device, scenario, setup, command/procedure, expected result, actual result, artifact, and status.
6. **Accessibility and performance evidence**: Check, tool or method, actual observation, threshold, limitation, and owner follow-up.
7. **Update and recovery procedure**: Worker activation, cache migration, feature disablement, preservation of pending work, prior-release restoration, and verification steps.
8. **Owner handoff**: Actions and decisions for the product owner, data and privacy owners, engineering owner, accessibility reviewer, and release owner. This is evidence for review, not deployment approval.
9. **Completion statement**: Separate requested, inspected, changed, executed, passed, failed, blocked, and unverified work. Do not claim installability, offline reliability, accessibility, or readiness beyond the captured browser evidence. End with the smallest safe next action.

## Variables to Replace

1. approved_pwa_feature_specification
2. repository_and_browser_context
3. offline_data_and_sync_contract
4. privacy_security_and_storage_boundaries
5. acceptance_criteria_and_authorized_scope

## How to Use

Open the existing web application repository in Codex and provide the approved PWA feature specification, supported browser and device targets, offline data and synchronization contract, privacy and storage rules, acceptance criteria, and exact allowed files and commands. Supply synthetic fixtures and existing manifest, service-worker, API, and test context where available, but do not paste credentials or production user data. Run it in an isolated environment with external APIs, notifications, analytics, push services, and deployment disabled or faked. Review the browser matrix, cache and storage boundaries, synchronization evidence, accessibility checks, and rollback procedure with the product, data, privacy, engineering, accessibility, and release owners before enabling the feature.

## Example Use Case

A field-service team has approved an offline inspection-note feature in its existing responsive web application. It gives Codex the repository, target browsers, a synthetic inspection dataset, approved cache and retention rules, an idempotent synchronization API contract, conflict behavior, and a feature-flag boundary. Codex implements the bounded PWA journey, tests offline launch, queued writes, duplicate replay, conflict handling, logout cleanup, storage limits, worker updates, keyboard status feedback, and rollback without connecting to production APIs or deploying the change.

## Tags

1. codex
2. Codex & Coding
3. feature-build
4. web-development
5. app-builder
6. responsive-design
7. mobile-ux
8. web-accessibility
9. performance
10. caching
11. state-management
12. sync-failure
13. deployment-safety

## Dates

Published: 2026-09-09
Updated: 2026-09-09