Progressive Web App Fundamentals¶

A Progressive Web App (PWA) is a website that uses a small set of standard web platform features (a secure context, a Web App Manifest and, usually, a service worker) to behave like an installed application: it can launch from the home screen or dock, open in its own window, keep working on a flaky network and integrate with the operating system. This section gives you the conceptual foundation for everything else on the site: what a PWA is and is not, where the idea came from, how it compares to native and hybrid apps, which building blocks it is made of, what browsers require before they offer installation, and a hands-on tutorial that ties it together.

What this section covers¶

The Fundamentals section is deliberately conceptual. Deep API references live in the Core Technologies, Capabilities and Engineering sections; here you build the mental model you need to use those references well. Each page answers one question in depth:

The three pillars: capable, reliable, installable¶

Most descriptions of PWAs reduce them to three adjectives. They are only useful if you know which concrete mechanisms sit behind each one, and how you would measure them.

Capable: the web platform can reach the device¶

"Capable" means your app can do the things users expect from an application, not just from a document: share content to other apps, receive shared files, open files from the OS file manager, read and write local files, show notifications, set an icon badge, talk to Bluetooth or USB hardware, handle a custom URL protocol, take payments and sign in with passkeys.

The mechanism is a large family of individual web APIs, most of which are gated by three layers of protection:

1. Secure context. Nearly every powerful API is only exposed on HTTPS (or localhost). Check it with window.isSecureContext.
2. User activation or permission. APIs such as navigator.share() require a recent user gesture (transient activation); APIs such as notifications or Bluetooth require an explicit permission grant.
3. Install state or display mode. Some capabilities only exist for installed apps: Web Push on iOS and iPadOS requires the site to be added to the Home Screen, Periodic Background Sync in Chromium requires installation, and manifest-declared integrations such as file_handlers, share_target or protocol_handlers only take effect once the OS knows about the app.

Capability support is uneven. Many APIs come from the cross-company Capabilities project (Project Fugu) and ship only in Chromium-based browsers; others, like Web Share, the Badging API and Web Push, are available in Safari too. The Device & OS Integration and Background & Engagement sections give per-API support tables.

Reliable: fast and resilient on any network¶

"Reliable" means the app starts quickly and behaves predictably whether the network is fast, slow, flaky or absent. The central mechanism is the service worker: a script the browser runs in a separate worker thread, outside any page, that receives a fetch event for every request made by the pages it controls. Because it can answer those requests from the Cache Storage API, from IndexedDB or from generated responses, it can:

• load the app shell instantly from a local cache, independent of network latency;
• show a meaningful offline page or cached content instead of the browser's error page;
• serve stale content immediately and update it in the background;
• queue writes made while offline and replay them later (with Background Sync where available, or on the next launch elsewhere).

Reliability is measurable: time-to-first-render on repeat visits, the percentage of navigations served from cache, and whether every route renders something useful when you toggle "Offline" in DevTools. The Caching & Offline section covers the strategies in depth.

Installable: a first-class place on the device¶

"Installable" means the user can add the app to their home screen, app launcher, dock, taskbar or Start menu, and launch it into its own window without browser UI. The mechanism is the Web App Manifest, a JSON file linked from your pages with <link rel="manifest">, which supplies the name, icons, start URL, scope, display mode and theme colors the OS needs to create an app entry.

What "installed" means varies by platform: on Android, Chrome mints a WebAPK (a real Android package); on desktop Chromium, the browser registers an app with the OS; on iOS and iPadOS, the system creates a Home Screen web app backed by WebKit; on macOS, Safari creates a Dock app. The Installation section and the Installability Criteria page have the platform-by-platform details.

The mental model: a website that progressively gains app capabilities¶

The word progressive is the most important part of the name. A PWA starts life as a normal website that works in every browser and every context: a link from search, a shared URL, a tab. It then layers on capabilities only where the browser supports them and only when the user opts in. Alex Russell's 2015 essay that introduced the term put it this way: sites "have to earn that right over time as you use them more and more. They progressively become 'apps'."

A useful way to reason about your own project is as a ladder in which each rung is optional and builds on the previous one:

The practical consequence: you never write if (isPWA). You write if ("serviceWorker" in navigator), if ("setAppBadge" in navigator), if (window.matchMedia("(display-mode: standalone)").matches) and so on. Every capability is detected individually, and the baseline experience never depends on any of them.

// Each rung of the ladder is detected and enabled independently.
// Nothing here is required for the site to work.
if ("serviceWorker" in navigator && window.isSecureContext) {
  navigator.serviceWorker.register("/sw.js").catch((error) => {
    // A failed registration must never break the page. Log and move on.
    console.warn("Service worker registration failed:", error);
  });
}

if ("setAppBadge" in navigator) {
  // Badging API: Chromium desktop and installed web apps in Safari.
  document.documentElement.classList.add("can-badge");
}

const standalone = window.matchMedia("(display-mode: standalone)");
const applyDisplayMode = () =>
  document.documentElement.classList.toggle("is-standalone", standalone.matches);
applyDisplayMode();
standalone.addEventListener("change", applyDisplayMode);

The What Is a PWA? page expands this into a complete feature-detection module.

Architecture at a glance¶

Every PWA, from a static blog to a large single-page application, has the same four moving parts: the page (your documents and their JavaScript), the manifest (static metadata read by the browser and the OS), the service worker (an event-driven script that controls pages within its scope) and storage (Cache Storage for HTTP responses, IndexedDB for structured data, and the Origin Private File System for files). The diagram shows how they relate.

flowchart LR
    User(["User"]) --> OS["OS launcher, dock or home screen"]
    OS -->|"launches start_url"| Page
    subgraph Browser["Browser engine"]
        Page["Page: HTML, CSS, JS"]
        SW["Service worker"]
        Caches[("Cache Storage")]
        IDB[("IndexedDB and OPFS")]
    end
    Manifest["manifest.webmanifest"] -->|"name, icons, scope, display"| Browser
    Browser -->|"install"| OS
    Page -->|"register /sw.js"| SW
    Page -->|"fetch requests"| SW
    SW -->|"cache hit"| Caches
    SW -->|"cache miss or refresh"| Network[("Network and origin server")]
    Page --> IDB
    SW --> IDB
    PushService["Push service"] -->|"push event"| SW

How to read it:

• The manifest flows to the browser, and the browser informs the OS. Your code never talks to the OS launcher directly. The browser reads the manifest, decides whether and how the app can be installed, and creates the OS-level entry (a WebAPK, an app shortcut, a Dock app, a Home Screen web app).
• The page registers the service worker, but the service worker controls the page. After registration and activation, every request made by a controlled page (including the navigation request for the next page) is dispatched as a fetch event to the service worker, which decides whether to answer from Cache Storage, from the network, or by constructing a response.
• Both the page and the service worker share the origin's storage. Cache Storage and IndexedDB are available in windows and workers alike, which is how a page can pre-populate data the service worker later serves offline.
• The push service talks only to the service worker. Push messages are delivered by the browser vendor's push service (Firebase Cloud Messaging for Chrome, Apple Push Notification service for Safari, Mozilla's autopush for Firefox) to the service worker, which can run even when no page is open. Safari's Declarative Web Push can even display a notification without running any service worker code.

Once you have this picture, the rest of the site maps onto it cleanly: Web App Manifest covers the left side, Service Workers the middle, and Caching & Offline the storage on the right. The Core Building Blocks page walks through each box and arrow in detail.

Recommended reading paths¶

Different readers need different entry points. Pick the path that matches your situation; each one ends with enough knowledge to ship a production PWA.

If you are new to PWAs¶

1. What Is a PWA?: definitions, the original characteristics, a minimal working example and the misconceptions to avoid.
2. Core Building Blocks: the system view of manifest, service worker, caches and HTTPS.
3. Tutorial: Your First PWA: build and install a real app step by step.
4. Installability Criteria: understand why a browser does or does not offer installation.
5. Service Worker Lifecycle and Caching Strategies: the two topics that cause the most production bugs.
6. Installation by Platform: what users on each OS actually see.

If you already ship web apps¶

1. Skim What Is a PWA?, focusing on "How an installed PWA actually runs" and "Hard limits".
2. Read Installability Criteria for the current per-browser rules; they changed substantially in 2023–2025.
3. Go straight to Service Workers, especially Updating Service Workers and Pitfalls & Anti-Patterns.
4. Review iOS & iPadOS for Safari-specific behavior.
5. Finish with the Production Checklist.

If you are evaluating PWAs for a product decision¶

1. PWA vs Native vs Hybrid for the trade-offs.
2. When to Build a PWA for decision criteria.
3. History & Evolution for context on platform support trajectories, including the 2024 EU Digital Markets Act episode on iOS.
4. Case Studies for sourced, real-world results.
5. Publishing to App Stores if store presence is a requirement.

Pages in this section¶

Where to go next¶

Once the fundamentals are in place, the rest of the site is organized around the four areas you will work in day to day.

Vocabulary used throughout this site¶

The same things are called by different names on different platforms, which causes real confusion in bug reports and specifications. This site uses the following terms consistently; the Glossary has the complete list.

Installed web app

The generic term for a web app that has an OS-level launcher entry and opens in its own window. "PWA" in this site's prose usually means the same thing, with the added expectation that the app was designed to be installed.

Home Screen web app

Apple's term for a site added to the Home Screen on iOS or iPadOS that opens as a web app rather than as a Safari tab. Since iOS 26, every site added to the Home Screen opens this way by default unless the user turns off "Open as Web App".

WebAPK

An Android package that Chrome (on devices with Google Play services) and Samsung Internet generate for an installed PWA, so the app appears in the launcher, in Android settings and can register intent filters for its URLs.

Standalone

The display mode in which the app has its own window without browser navigation UI. Detect it with the (display-mode: standalone) media query. Safari additionally exposes the legacy non-standard navigator.standalone boolean on iOS and iPadOS and, since Safari 17, on macOS (true in Dock web apps); check it first on Apple platforms, because an iOS web app whose manifest says standalone matches (display-mode: fullscreen).

Scope

The URL prefix that belongs to the app. It exists twice: the manifest scope (which navigations stay inside the app window) and the service worker scope (which pages the worker controls). They are independent and frequently confused.

Controlled page

A document whose requests are routed through a service worker. A page is only controlled if a service worker was active for its scope when the navigation started, or if the worker called clients.claim().

App shell

The minimal HTML, CSS and JavaScript needed to render the application's chrome, cached so that the UI appears instantly while content loads. See App Shell Model.

Further reading¶

On this site

• What Is a PWA?
• History & Evolution
• Core Building Blocks
• Installability Criteria
• Tutorial: Your First PWA
• Service Worker Lifecycle
• Glossary

External references

• Progressive web apps (MDN)
• Learn PWA (web.dev)
• Web Application Manifest (W3C)
• Service Workers (W3C)
• Progressive Web Apps: Escaping Tabs Without Losing Our Soul (Alex Russell, 2015)