Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

The Building Blocks of a PWA

See how HTTPS, the web app manifest, service workers and the Cache API fit together in a PWA, and how the browser decides that a site is installable.

Every Progressive Web App is assembled from the same few parts. None of them is exotic: a JSON file, a script and a secure connection. What makes them powerful is how the browser combines them. Knowing the role of each part makes the rest of the course easier, because every later lesson goes deeper into one of these blocks.

This lesson gives you the map. You will see which part does what, how the browser decides a site is installable, and where each part lives in your project.

HTTPS: the foundation

Service workers can intercept every request your page makes and rewrite the responses. In the wrong hands that is a perfect way to attack users, so browsers only allow service workers on secure contexts: pages served over https://. The single exception is localhost (and 127.0.0.1), so you can develop without certificates.

Besides service workers, many other APIs used by PWAs also need a secure context: push notifications, the install prompt, geolocation, clipboard access and more. You can check this in JavaScript:

JavaScript
console.log(window.isSecureContext); // true on https:// and localhost

In production, get a free certificate (most hosts provide one automatically) and redirect all http:// traffic to https://.

The web app manifest

The manifest is a JSON file, linked from every page:

HTML
<link rel="manifest" href="/manifest.webmanifest">

It describes the app: its name, icons, start URL, colors and display mode. Browsers read it to build the install dialog, the home screen icon, the splash screen and the window frame. Chapter 2 covers it in detail. A small example:

JSON
{
  "name": "Trail Notes",
  "short_name": "Notes",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0b6e4f",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

The service worker

A service worker is a JavaScript file that the browser runs in the background, separate from your page. It has no access to the DOM. Instead it listens for events:

  • install and activate for its own lifecycle,
  • fetch for every network request made by pages it controls,
  • push and sync for notifications and background work.

Because it can answer a fetch event from a cache, it is what makes offline possible. The skeleton looks like this (read-only; real service workers cannot run in this page's sandbox):

JavaScript
// sw.js
self.addEventListener('install', (event) => {
  // prepare caches
});

self.addEventListener('fetch', (event) => {
  // decide how to answer each request
});

Storage: Cache API and friends

A service worker needs somewhere to keep responses. The Cache API stores Request/Response pairs by name. For app data (notes, carts, drafts) you use IndexedDB, a browser database. The two together mean: Cache API for files, IndexedDB for data. You will learn the Cache API in chapter 4 and IndexedDB in the offline chapter.

The window, the worker and the network

Here is how the pieces talk to each other at runtime:

sequenceDiagram
  participant Page
  participant SW as Service worker
  participant Cache
  participant Net as Network
  Page->>SW: fetch /styles.css
  SW->>Cache: match(request)
  alt found
    Cache-->>SW: cached response
  else not found
    SW->>Net: fetch(request)
    Net-->>SW: network response
  end
  SW-->>Page: response

The page never knows whether the answer came from the cache or from the network. That is the power and the danger of the service worker.

How the browser decides a site is installable

Chromium-based browsers run an installability check. A page qualifies when roughly the following holds:

  1. It is served over HTTPS (or is on localhost).
  2. It links to a manifest with name or short_name, icons (a 192 px and a 512 px icon), start_url and a display of standalone, fullscreen or minimal-ui.
  3. The site is not already installed.

Newer Chrome versions no longer require a fetch handler, but adding one is still how you get real offline support. Other browsers apply their own rules: Safari on iOS lets users add almost any site to the home screen, and Firefox on desktop does not offer installation at all (Firefox on Android does). Treat installability as an enhancement.

The following stand-in implements the core of that check so you can see the rules as code. It runs on plain objects, not on a real manifest, and the rules are simplified.

JS Stand-in: a tiny installability checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Where things live in a project

A minimal PWA project looks like this:

TEXT
my-pwa/
  index.html
  app.js
  styles.css
  manifest.webmanifest
  sw.js            <- must be served from the root to control the whole site
  icons/
    icon-192.png
    icon-512.png

Note the location of sw.js: a service worker can only control pages at or below its own path (its scope). Putting it at the root lets it control everything. You will use this in lesson 3 of chapter 3.

Seeing the parts in DevTools

In Chrome or Edge, open DevTools and use the Application panel. The sections "Manifest", "Service workers" and "Cache storage" show exactly the three blocks of this lesson. The Manifest section even lists installability problems in plain language. You will use this panel throughout the course; the browser support lesson in this chapter covers it in detail.

When something does not work, ask which block is at fault: is the origin secure, is the manifest valid, is the service worker registered and in control? Most PWA bugs are one of these three.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must service workers be served over HTTPS (except on localhost)?

    A service worker sits between the page and the network, so an attacker on an insecure connection could abuse it.
  2. 2. Where would you store a user's notes for offline use?

    App data belongs in IndexedDB. The Cache API is meant for request/response pairs such as files.
  3. 3. What does a service worker NOT have access to?

    Workers run apart from the page and cannot touch the DOM.
  4. 4. Where should sw.js usually be placed if it should control the whole site?

    A service worker's scope defaults to its own folder, so the root location controls everything.

Summary

  • A PWA is HTTPS plus a manifest plus a service worker.
  • The manifest describes how the app looks and installs; the service worker controls requests.
  • Cache API stores files, IndexedDB stores data.
  • Browsers use an installability check based mostly on the manifest and a secure origin.
  • DevTools' Application panel shows all three blocks.

Next: The App Shell Model