Service Workers Pwa Knowledge Patch

Service Workers and Progressive Web Apps

Use this skill when implementing or reviewing service-worker static routing, web app manifests, installed-app detection, installed-PWA navigation, or Workbox window integration.

Treat browser and platform support as part of the design. Manifest standards, service-worker APIs, installed-app relationships, and Workbox helpers do not share one support matrix.

Reference index

Compatibility changes and broken assumptions

Installed desktop PWAs may capture links automatically

In Chrome 139 on Windows, macOS, and Linux, an in-scope capturable link opens in an installed PWA by default. Do not assume every ordinary link navigation remains in a browser tab.

Capture applies after Chrome determines that navigation creates a new frame without an auxiliary browsing context, checks manifest scope, and honors the user's opt-out preference. It falls back to a tab when no controlling PWA is available or the user opted out. Do not assume the same behavior on ChromeOS.

Specification-level installability is not an install prompt guarantee

The Web App Manifest specification treats every website as an installable web application. The user agent still decides whether and how to offer installation. Keep product-facing installation logic separate from the specification's installability definition.

Identity updates are consent-sensitive

Although a manifest is fetched and processed on each page load, changes to name, short_name, icons, and their localized forms should require express permission before being applied. Apply other non-security-sensitive changes immediately, but do not design identity changes as silent updates.

A changed icon src counts as an update. A visually insignificant icon change may be treated as non-security-sensitive. Locale selection may switch the localized identity automatically, but the change should be presented when the application next opens.

Storefront members moved out of the core manifest specification

Look to the Manifest Application Information companion specification for categories, description, iarc_rating_id, and screenshots. Do not treat their absence from the core draft as removal from the broader manifest model.

Static routing needs a feature fallback

InstallEvent.addRoutes() has limited availability and is not Baseline. Feature-test it and preserve normal service-worker or network behavior where it is unavailable.

Manifest quick reference

Localize identity and shortcut metadata with language maps

Add sibling *_localized language maps to:

• top-level name, short_name, and icons;
• shortcut name, short_name, description, and icons.

Keep the unsuffixed member as the fallback. A localized text entry may be a plain string or an object containing value plus optional lang and dir. Object defaults come from the language-map key and manifest-wide dir. Localized image entries are arrays of image resources.

{
  "lang": "en-US",
  "dir": "ltr",
  "name": "Color Picker",
  "name_localized": {
    "de": "Farbwähler",
    "ar": { "value": "منتقي الألوان", "dir": "rtl" }
  },
  "icons": [{ "src": "/icons/default.png", "sizes": "256x256" }],
  "icons_localized": {
    "fr": [{ "src": "/icons/fr.png", "sizes": "256x256" }]
  }
}

Expect the user agent to choose the best language match.

Supply dark theme colors

Use color_scheme_dark only to override theme_color and background_color:

{
  "background_color": "#fff",
  "theme_color": "red",
  "color_scheme_dark": {
    "background_color": "#000",
    "theme_color": "hotpink"
  }
}

The override follows the operating-system dark theme subject to user preferences such as accessibility settings. Color values survive processing only when they can be converted to sRGB without external data. lab() and color(display-p3 ...) are convertible; a custom profile requiring @color-profile is ignored.

Static routing quick reference

Register predictable routes during install so network and cache sources can be selected without starting the worker.

self.addEventListener("install", event => {
  const added = event.addRoutes([
    {
      condition: { urlPattern: "/static/*" },
      source: { cacheName: "static-v3" }
    },
    {
      condition: { urlPattern: "/api/*", requestMethod: "GET" },
      source: "race-network-and-fetch-handler"
    }
  ]);
  event.waitUntil(added);
});

Choose sources deliberately:

Install a fetch listener before using either handler-backed source or addRoutes() rejects with TypeError.

Leaf conditions are ANDed. An or or not boolean node must be the condition object's sole member. Respect first-match ordering, the accumulated 1024-condition budget, and maximum nesting depth 10.

Pass the returned promise to waitUntil() when an invalid or over-limit route must fail installation. Calling addRoutes() keeps installation alive through a separate always-fulfilled internal promise, so route rejection alone does not otherwise fail the install.

Installation detection quick reference

Call navigator.getInstalledRelatedApps() only in HTTPS contexts and treat an empty result as normal:

const related = await navigator.getInstalledRelatedApps?.() ?? [];

The query is not an installed-app enumerator. It considers only the first three manifest related_applications entries, and returns only installed apps that are declared by the site and mutually verified.

Select the relationship recipe by target:

Do not depend on manifest min_version or fingerprints filters: browsers do not implement them for these queries. Verify returned details in application logic when version or certificate identity matters.

Desktop self-detection requires the page to share the PWA origin and be inside manifest scope. The webapp entry's id is required on desktop, while Android does not require it. Read the full platform recipes before editing declarations.

Workbox lifecycle quick reference

Attach lifecycle listeners before register(). Registration normally waits for the window load event; pass {immediate: true} to register sooner.

const wb = new Workbox("/sw.js");
wb.addEventListener("waiting", event => showUpdatePrompt(event));
await wb.register({immediate: true});

Interpret event flags instead of treating every event as a fresh update:

• isUpdate distinguishes initial installation from an update.
• isExternal identifies a worker installed outside this Workbox instance.
• wasWaitingBeforeRegister means the worker was already waiting before registration, including the common reload case.

messageSW() selects a matching waiting worker before an active worker at registration time; otherwise it waits for a matching installing worker. Its promise resolves only when the worker replies through event.ports[0].

addEventListener("message", event => {
  if (event.data.type === "GET_VERSION") {
    event.ports[0].postMessage("2.0.0");
  }
});

The default workbox-routing router handles CACHE_URLS messages and caches only URLs matching registered routes. For a separately constructed Router, call addCacheListener() explicitly.

Review checklist

• Check browser, operating-system, and library support independently.
• Keep unsuffixed manifest members as localization fallbacks.
• Require consent for visible identity changes.
• Feature-test static routing and preserve a fallback request path.
• Validate route condition shape, source prerequisites, order, and quotas.
• Use waitUntil(addRoutesPromise) when route failure must fail installation.
• Configure installed-app declarations and verification in both directions.
• Do not use installed-related-app results as arbitrary app enumeration.
• Register Workbox listeners before registration.
• Make every messageSW() request produce an explicit port reply.