Tutorial: Build Your First PWA¶

This tutorial builds Pocket Notes, a complete Progressive Web App with no framework and no build step. Notes live in IndexedDB, a service worker precaches the app shell so the app launches with no network, a web app manifest makes it installable, and a toast tells users when a new version is ready. Every file appears in full, and all of them were run together end to end in headless Chrome 153: installability check, offline launch, the update flow and a deployment behind a redirecting host. Each step also explains the platform behavior underneath, from the maskable icon safe zone to why a cached redirect breaks offline navigation, so you can apply the same patterns to your own site.

What you will build¶

Pocket Notes is small enough to read in one sitting and complete enough to ship. It has everything a production PWA needs and nothing else:

• Notes CRUD. You can create, edit, delete and filter notes. Every note is an IndexedDB record, so data survives restarts and works offline.
• Offline launch. The HTML, CSS, JavaScript, manifest and icons are precached at install time. Cold starts with no connection behave exactly like online starts.
• An offline fallback page. Navigations to pages that were never cached get a styled offline.html instead of the browser's error page.
• Installability everywhere. A custom Install app button appears in Chrome, Edge and Samsung Internet. iOS and iPadOS users get a one-time hint that explains Share > Add to Home Screen. Safari on macOS and Firefox for Android can install through their own menus.
• An app shortcut. Long-pressing (Android) or right-clicking (desktop) the installed icon offers New note.
• Safe updates. A new deployment installs in the background and waits. A toast offers to reload. Unsaved text survives that reload.
• Multi-tab consistency. A BroadcastChannel keeps every open window's list in sync.

The architecture has three browser storage areas and one worker:

flowchart LR
    subgraph PAGE["Page: index.html"]
        APP["app.js: UI and notes CRUD"]
        DB["db.js: IndexedDB wrapper"]
        PWA["pwa.js: registration, updates, install UI"]
    end
    SW["sw.js: service worker"]
    IDB[("IndexedDB: pocket-notes")]
    CS[("Cache Storage: precache and runtime")]
    SS[("sessionStorage: unsaved draft")]
    NET["Static host"]
    APP --> DB --> IDB
    APP --> SS
    APP --> PWA
    PWA -- "register and postMessage" --> SW
    PAGE -- "every same-origin request" --> SW
    SW --> CS
    SW -- "cache miss" --> NET

The split between the two big stores is the most important design decision in any offline-capable app. Cache Storage holds code: files that change only when you deploy, keyed by URL, and replaced wholesale on each version. IndexedDB holds data: records the user creates, which must never be deleted by a deployment. The Core Building Blocks page explains where each browser primitive fits, and Offline-First Data & Sync covers syncing data to a server, which this tutorial deliberately leaves out.

Before you start¶

You need:

• Node.js 20.9 or later for the dev tooling. sharp 0.35, which renders the icons, declares node >= 20.9.0 in its package metadata. If you only want to serve the finished files, Python 3 works too.
• Chrome or Edge for DevTools. The PWA panels in Chromium DevTools are the most complete, and Chromium is the only engine that fires beforeinstallprompt.
• Optionally, an Android phone (USB debugging) or an iPhone or iPad to try the real install flows.

You don't need a framework, a bundler, TypeScript or a certificate. Everything runs as native ES modules. The app uses crypto.randomUUID(), BroadcastChannel, the <template> element and replaceChildren(), which every current browser supports. The browser support table near the end lists the versions.

If you're new to the moving parts, skim What Is a PWA? first. If you want to know exactly which conditions each browser checks before offering installation, Installability Criteria is the companion to this page.

Step 1: Create the project structure¶

Create this layout. Everything under public/ is what you deploy, and nothing outside it ever reaches users:

pocket-notes/
├── package.json              # dev tooling only: serve, sharp, puppeteer
├── icon-src/
│   ├── source.svg            # "any" icon artwork (rounded tile, transparent corners)
│   └── maskable.svg          # full-bleed artwork for maskable icons
├── tools/
│   ├── make-icons.mjs        # renders every PNG icon from icon-src/
│   ├── stamp-version.mjs     # writes a content hash into sw.js before a deploy
│   └── smoke-test.mjs        # automated installability and offline checks
└── public/                   # the deployable app: publish this directory
    ├── index.html
    ├── offline.html
    ├── styles.css
    ├── app.js
    ├── db.js
    ├── pwa.js
    ├── sw.js
    ├── manifest.webmanifest
    ├── serve.json            # local dev server configuration
    ├── _headers              # response headers for Netlify and Cloudflare Pages
    ├── icons/                # generated by tools/make-icons.mjs
    └── screenshots/          # wide.png (1280x800) and narrow.png (750x1334)

Two placement rules matter here.

sw.js sits at the root of the deployed directory. A service worker's maximum scope is the directory its script is served from. A worker at /js/sw.js can control /js/ and below, but never /index.html, unless the server sends a Service-Worker-Allowed header that widens it. Putting sw.js next to index.html gives it control of the whole app with no special headers. Registration & Scope walks through the scope algorithm.

Tooling stays outside public/. Hosting providers publish a directory. If that directory were the project root, node_modules/, the icon sources and your scripts would all become public URLs, and a /* cache rule would apply to them too.

Create the folders and package.json:

mkdir -p pocket-notes/{icon-src,tools,public/icons,public/screenshots}
cd pocket-notes

{
  "name": "pocket-notes",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "serve public",
    "icons": "node tools/make-icons.mjs",
    "stamp": "node tools/stamp-version.mjs",
    "smoke": "node tools/smoke-test.mjs http://localhost:3000/"
  },
  "devDependencies": {
    "puppeteer": "^25.12.0",
    "serve": "^14.2.6",
    "sharp": "^0.35.4"
  }
}

Then install the dev dependencies:

npm install

Each dependency has one job. serve is a static file server for local development, sharp renders SVG artwork to PNG icons, and puppeteer drives Chrome for the automated checks in Step 11. Puppeteer downloads its own copy of Chrome for Testing during installation. If you don't want that download, drop it from package.json and skip the automated check; nothing else depends on it. None of these packages ship to users.

Step 2: Write index.html and its head tags¶

The page is plain, semantic HTML. It works as a normal website before any of the PWA pieces exist, which is the point of progressive enhancement: the manifest and service worker add capabilities, but the app never depends on them to render.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <!-- viewport-fit=cover lets the layout extend under notches; CSS adds safe-area padding back -->
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
  <title>Pocket Notes</title>
  <meta name="description" content="Offline-first notes that live on your device.">

  <!-- Web app manifest: identity, icons, display mode, shortcuts -->
  <link rel="manifest" href="manifest.webmanifest">

  <!-- Browser UI color; the media queries give dark mode its own value -->
  <meta name="theme-color" content="#1f6f5c" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#12332b" media="(prefers-color-scheme: dark)">
  <meta name="color-scheme" content="light dark">

  <!-- Icons: tab favicon (SVG + PNG fallback) and the iOS/iPadOS Home Screen icon -->
  <link rel="icon" href="icons/favicon.svg" type="image/svg+xml">
  <link rel="icon" href="icons/favicon-32.png" sizes="32x32" type="image/png">
  <link rel="apple-touch-icon" href="icons/apple-touch-icon.png">

  <link rel="stylesheet" href="styles.css">
  <!-- Module scripts are deferred: they run after the document is parsed -->
  <script type="module" src="app.js"></script>
</head>
<body>
  <header class="app-bar">
    <h1 class="app-title">Pocket Notes</h1>
    <span id="net-status" class="net-status" role="status" aria-live="polite"></span>
    <button type="button" id="install-button" class="btn btn-install" hidden>Install app</button>
  </header>

  <main class="layout">
    <form id="note-form" class="editor" autocomplete="off">
      <label for="note-text" class="visually-hidden">Note text</label>
      <textarea id="note-text" name="text" rows="4" maxlength="10000" required
                placeholder="Write a note… (Ctrl/⌘ + Enter to save)"></textarea>
      <div class="editor-actions">
        <button type="submit" id="save-button" class="btn btn-primary">Save note</button>
        <button type="button" id="cancel-edit" class="btn" hidden>Cancel</button>
      </div>
    </form>

    <section class="notes" aria-labelledby="notes-heading">
      <div class="list-header">
        <h2 id="notes-heading">Notes <span id="note-count" class="count"></span></h2>
        <input type="search" id="filter" class="filter" placeholder="Filter" aria-label="Filter notes">
      </div>
      <ul id="note-list" class="note-list"></ul>
      <p id="empty-state" class="empty" hidden>
        No notes yet. Notes are stored on this device and work offline.
      </p>
    </section>
  </main>

  <aside id="ios-install-hint" class="ios-hint" hidden>
    <p>Install Pocket Notes: tap <strong>Share</strong> (in Safari’s <strong>⋯</strong> menu), then <strong>Add to Home Screen</strong>.</p>
    <button type="button" id="ios-hint-dismiss" class="btn">Got it</button>
  </aside>

  <div id="update-toast" class="toast" role="alert" hidden>
    <span>A new version of Pocket Notes is ready.</span>
    <button type="button" id="update-reload" class="btn btn-primary">Reload</button>
    <button type="button" id="update-dismiss" class="btn">Later</button>
  </div>

  <template id="note-template">
    <li class="note">
      <p class="note-text"></p>
      <div class="note-meta">
        <time class="note-time"></time>
        <span class="note-actions">
          <button type="button" class="btn btn-small" data-action="edit">Edit</button>
          <button type="button" class="btn btn-small btn-danger" data-action="delete">Delete</button>
        </span>
      </div>
    </li>
  </template>

  <noscript><p class="empty">Pocket Notes needs JavaScript to store notes on your device.</p></noscript>
</body>
</html>

What every head tag does¶

The body: structure that survives without JavaScript¶

A few details in the markup carry weight later:

• hidden everywhere. The install button, the update toast and the iOS hint all start hidden. Script reveals them only when they apply. Step 3 makes sure CSS can never accidentally show them.
• role="status" with aria-live="polite" on #net-status makes screen readers announce "Offline" and error messages without stealing focus. The toast uses role="alert", which interrupts, because an update prompt needs a decision.
• A <template> for note items. Cloning a template is faster than building elements one by one, and it keeps the markup in HTML where designers can edit it.
• maxlength="10000" and required are the first line of validation. IndexedDB would store a much larger string, but a notes app has no reason to.
• <noscript> explains why nothing works with JavaScript disabled. Storage on the device needs script.

Step 3: Style the app for browser tabs and standalone windows¶

An installed PWA runs in two very different environments: a browser tab with an address bar, and a standalone window with no browser interface at all, sometimes drawn under a notch or a home indicator. The stylesheet handles both:

/* ---------- Design tokens ---------- */
:root {
  color-scheme: light dark;
  --bg: #f7f4ed;
  --surface: #ffffff;
  --text: #1d2521;
  --muted: #5b6761;
  --accent: #1f6f5c;
  --accent-contrast: #ffffff;
  --danger: #b3261e;
  --border: #d9d4c7;
  --radius: 12px;
  --bar-height: 56px;
  /* env() values are 0 in a normal browser tab and non-zero under notches / home indicators */
  --safe-top: env(safe-area-inset-top, 0px);
  --safe-right: env(safe-area-inset-right, 0px);
  --safe-bottom: env(safe-area-inset-bottom, 0px);
  --safe-left: env(safe-area-inset-left, 0px);
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #101815;
    --surface: #18221e;
    --text: #e6ece9;
    --muted: #9aa8a1;
    --accent: #12332b;
    --accent-contrast: #e6ece9;
    --danger: #ffb4ab;
    --border: #2c3a34;
  }
}

/* ---------- Base ---------- */
*, *::before, *::after { box-sizing: border-box; }

/* The hidden attribute must win over any display value set below */
[hidden] { display: none !important; }

html { -webkit-text-size-adjust: 100%; text-size-adjust: 100%; }

body {
  margin: 0;
  min-height: 100dvh;
  font: 16px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
  background: var(--bg);
  color: var(--text);
  padding-left: var(--safe-left);
  padding-right: var(--safe-right);
}

.visually-hidden {
  position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0;
  overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0;
}

/* ---------- App bar ---------- */
.app-bar {
  position: sticky;
  top: 0;
  z-index: 10;
  display: flex;
  align-items: center;
  gap: 12px;
  min-height: calc(var(--bar-height) + var(--safe-top));
  padding: var(--safe-top) 16px 0;
  background: var(--accent);
  color: var(--accent-contrast);
}
.app-title { flex: 1; margin: 0; font-size: 1.125rem; font-weight: 650; }
.net-status { font-size: 0.8125rem; opacity: 0.9; }

/* ---------- Buttons ---------- */
.btn {
  appearance: none;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-height: 44px;               /* comfortable touch target */
  padding: 0 16px;
  border: 1px solid var(--border);
  border-radius: 999px;
  background: var(--surface);
  color: var(--text);
  font: inherit;
  font-weight: 600;
  text-decoration: none;
  cursor: pointer;
}
.btn:focus-visible { outline: 3px solid var(--accent); outline-offset: 2px; }
.btn-primary { background: var(--accent); border-color: var(--accent); color: var(--accent-contrast); }
.btn-install { border-color: currentColor; background: transparent; color: inherit; min-height: 36px; }
.btn-small { min-height: 36px; padding: 0 12px; font-size: 0.875rem; }
.btn-danger { color: var(--danger); }
@media (prefers-color-scheme: dark) {
  .btn-primary { background: #5cc2a5; border-color: #5cc2a5; color: #0b1512; }
}

/* ---------- Layout ---------- */
.layout {
  max-width: 720px;
  margin: 0 auto;
  padding: 16px 16px calc(96px + var(--safe-bottom));
}

.editor {
  display: grid;
  gap: 12px;
  padding: 16px;
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: var(--radius);
}
.editor textarea {
  width: 100%;
  min-height: 6.5em;
  padding: 12px;
  resize: vertical;
  border: 1px solid var(--border);
  border-radius: 8px;
  background: var(--bg);
  color: var(--text);
  font: inherit;
}
.editor-actions { display: flex; gap: 8px; }

.list-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  margin: 24px 0 8px;
}
.list-header h2 { margin: 0; font-size: 1rem; }
.count { color: var(--muted); font-weight: 400; }
.filter {
  width: min(50%, 220px);
  min-height: 36px;
  padding: 0 12px;
  border: 1px solid var(--border);
  border-radius: 999px;
  background: var(--surface);
  color: var(--text);
  font: inherit;
}

.note-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 8px; }
.note {
  padding: 12px 16px;
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: var(--radius);
}
.note.is-editing { outline: 2px solid var(--accent); }
.note-text { margin: 0 0 8px; white-space: pre-wrap; overflow-wrap: anywhere; }
.note-meta { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
.note-time { color: var(--muted); font-size: 0.8125rem; }
.note-actions { display: flex; gap: 4px; }
.empty { color: var(--muted); text-align: center; padding: 32px 16px; }

/* ---------- Toast and iOS hint (fixed to the bottom, above the home indicator) ---------- */
.toast,
.ios-hint {
  position: fixed;
  left: calc(16px + var(--safe-left));
  right: calc(16px + var(--safe-right));
  bottom: calc(16px + var(--safe-bottom));
  z-index: 20;
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px 12px;
  max-width: 560px;
  margin: 0 auto;
  padding: 12px 16px;
  border-radius: var(--radius);
  background: var(--text);
  color: var(--bg);
  box-shadow: 0 8px 24px rgb(0 0 0 / 0.25);
}
.toast span, .ios-hint p { flex: 1 1 200px; margin: 0; }

/* ---------- Installed (standalone) mode tweaks ---------- */
@media (display-mode: standalone), (display-mode: fullscreen), (display-mode: minimal-ui) {
  /* Already installed: never offer installation again */
  .btn-install { display: none !important; }
  /* App chrome should not be selectable like document text */
  .app-bar { -webkit-user-select: none; user-select: none; }
  /* No pull-to-refresh / scroll chaining at the document edge */
  html, body { overscroll-behavior-y: none; }
}

Safe areas: viewport-fit=cover and env()¶

Phones with notches, rounded corners and gesture bars report the unsafe regions of the screen through four environment variables: safe-area-inset-top, -right, -bottom and -left. They're non-zero only when the page is allowed to draw under those regions, which is what viewport-fit=cover in the viewport tag requests. The stylesheet copies them into custom properties once (with a 0px fallback) and then uses them in three places:

1. The app bar grows by --safe-top and pads its content down by the same amount. In a standalone iOS app or an Android app drawn edge to edge, the green bar extends behind the status area while the title stays readable.
2. The body pads left and right, which matters in landscape on notched phones.
3. The fixed toast and iOS hint sit 16px above --safe-bottom, so the home indicator never covers the Reload button.

env() has worked in every major engine for years (Chrome 69, Firefox 65 and Safari 11.1, according to MDN's compatibility data). In an ordinary desktop tab all four values are 0, so the same CSS is correct everywhere.

Styling the installed app with the display-mode media query¶

The display-mode media feature matches the display mode the page is actually running in: browser in a tab, and standalone, fullscreen or minimal-ui when installed with those modes. Chromium also supports window-controls-overlay, and newer engines add picture-in-picture. The query in the stylesheet does three things when installed:

• Hides the install button with !important, because offering to install an installed app is confusing. The script also never reveals it there, since beforeinstallprompt doesn't fire for installed apps, but CSS makes the guarantee unconditional.
• Disables text selection on the app bar, so a long-press on the title doesn't start a selection the way it would on a document.
• Sets overscroll-behavior-y: none on the root, which disables pull-to-refresh and the rubber-band bounce at the document edge. Native apps don't refresh when you overscroll, and an accidental reload would throw away unsaved input.

The Display Modes page covers the fallback chain between modes and the matching JavaScript API, matchMedia('(display-mode: standalone)'), which pwa.js uses in Step 9.

Three smaller details¶

• [hidden] { display: none !important; } fixes a classic bug. The user-agent stylesheet implements hidden as display: none, but any author rule that sets display, such as .toast { display: flex }, beats it. The toast would then show on page load.
• min-height: 100dvh uses the dynamic viewport unit, which tracks the visible height as mobile browser toolbars collapse and expand. 100vh would be taller than the visible area in a mobile tab. dvh is supported in Chrome 108, Firefox 101 and Safari 15.4 and later.
• 44 px touch targets on buttons follow common platform guidance for comfortable tapping. The Accessibility page explains the target-size criteria.

Step 4: Store notes in IndexedDB (db.js)¶

Notes need storage that is asynchronous, transactional, survives restarts and holds structured objects. IndexedDB is the only web storage API that does all of that. localStorage is synchronous (every read blocks the main thread), stores only strings, and isn't available in workers.

The raw IndexedDB API is event-based and verbose, so db.js wraps it in four promise-returning functions. It has no dependencies. In a larger app you might use a small wrapper library such as idb, but the raw version shows what actually happens:

// db.js — a small promise wrapper around IndexedDB for the "notes" object store.
const DB_NAME = 'pocket-notes';
const DB_VERSION = 1;
const STORE = 'notes';

let dbPromise = null;

/** Opens (and, on first run, creates) the database. The connection is reused. */
function openDatabase() {
  if (dbPromise) return dbPromise;

  dbPromise = new Promise((resolve, reject) => {
    if (!('indexedDB' in globalThis)) {
      reject(new Error('IndexedDB is not available in this browser.'));
      return;
    }

    const request = indexedDB.open(DB_NAME, DB_VERSION);

    // Runs only when the on-disk version is lower than DB_VERSION.
    // Add one `if (oldVersion < N)` block per schema version; never edit old blocks.
    request.onupgradeneeded = (event) => {
      const db = request.result;
      if (event.oldVersion < 1) {
        const store = db.createObjectStore(STORE, { keyPath: 'id' });
        store.createIndex('updatedAt', 'updatedAt');
      }
    };

    request.onsuccess = () => {
      const db = request.result;
      // Another tab (or a new deploy) wants a higher version: close so its upgrade can proceed.
      db.onversionchange = () => {
        db.close();
        dbPromise = null;
      };
      // The browser closed the connection (e.g. the user cleared site data).
      db.onclose = () => {
        dbPromise = null;
      };
      resolve(db);
    };

    request.onerror = () => {
      dbPromise = null;
      reject(request.error);
    };

    // An older connection in another tab has not closed yet; the open stays pending.
    request.onblocked = () => {
      console.warn('[db] Upgrade blocked: close other Pocket Notes tabs.');
    };
  });

  return dbPromise;
}

/**
 * Runs `callback(store)` in a transaction and resolves once the transaction commits.
 * The callback must issue its requests synchronously. If it returns an IDBRequest,
 * that request's result is the resolved value; any other return value is passed through.
 */
async function withStore(mode, callback) {
  const db = await openDatabase();
  return new Promise((resolve, reject) => {
    const tx = db.transaction(STORE, mode);
    const returned = callback(tx.objectStore(STORE));
    let result = returned;

    if (returned instanceof IDBRequest) {
      returned.onsuccess = () => {
        result = returned.result;
      };
    }

    // Resolve on "complete", not on request success: only then is the write durable.
    tx.oncomplete = () => resolve(result);
    tx.onerror = () => reject(tx.error);
    tx.onabort = () => reject(tx.error ?? new DOMException('Transaction aborted', 'AbortError'));
  });
}

/** All notes, newest first (walks the updatedAt index backwards). */
export function getAllNotes() {
  return withStore('readonly', (store) => {
    const notes = [];
    const cursorRequest = store.index('updatedAt').openCursor(null, 'prev');
    cursorRequest.onsuccess = () => {
      const cursor = cursorRequest.result;
      if (cursor) {
        notes.push(cursor.value);
        cursor.continue();
      }
    };
    return notes; // fully populated by the time the transaction completes
  });
}

export function getNote(id) {
  return withStore('readonly', (store) => store.get(id));
}

/** Inserts or replaces a note; resolves with its key. */
export function putNote(note) {
  return withStore('readwrite', (store) => store.put(note));
}

export function deleteNote(id) {
  return withStore('readwrite', (store) => store.delete(id));
}

Each note is a plain object: { id, text, createdAt, updatedAt }. The store uses id as its key (keyPath: 'id'), and an index on updatedAt gives a newest-first listing without sorting in JavaScript.

Why the promise resolves on complete, not on success¶

A request's success event only means that operation succeeded inside a transaction that can still fail. The transaction commits after its last request, and the commit itself can fail, for example with a QuotaExceededError when the origin runs out of space. That failure aborts the whole transaction and rolls back every write in it. withStore() therefore captures the request's result on success but resolves the promise only on the transaction's complete event. When putNote() resolves, the note is committed.

The same design explains the rule in the comment: the callback must issue its requests synchronously. A transaction commits automatically when control returns to the event loop with no pending requests. If you await anything unrelated inside the callback (a fetch(), a timer), the transaction has already committed by the time your code resumes, and the next request throws TransactionInactiveError. getAllNotes() stays within the rule by continuing the cursor from its own success callback, which keeps the transaction alive until the cursor finishes.

Schema versioning with onupgradeneeded¶

indexedDB.open(name, version) compares the requested version with the one on disk. When the requested version is higher, or the database doesn't exist, it fires upgradeneeded in a special versionchange transaction. That's the only place where you can create or delete object stores and indexes. The if (event.oldVersion < 1) pattern scales: when version 2 adds a tags index, you add an if (event.oldVersion < 2) block below the first one. A user upgrading from version 0, 1 or 2 runs exactly the blocks they need, in order. Never edit an old block, because users who already ran it will never run it again.

versionchange, blocked and close¶

Schema upgrades collide with other open tabs. If tab A has version 1 open and a newly deployed tab B opens version 2, the browser fires versionchange on A's connection. db.js responds by closing that connection and clearing the cached promise, so A's next call reopens the database at the new version. If a connection doesn't close, B's open request fires blocked and waits. onblocked logs a warning here; a production app might show "Close other tabs to finish updating". The close handler covers the rarer case where the browser closes the connection itself, for example when the user clears site data.

The IndexedDB page covers indexes, key ranges, cursors, durability hints and performance in depth.

Step 5: Write the UI logic (app.js)¶

app.js is the only module the HTML loads directly. It renders the list, handles the form and wires everything else together:

// app.js — UI logic: render, create, edit, delete and filter notes.
import { getAllNotes, getNote, putNote, deleteNote } from './db.js';
import { initPwa } from './pwa.js';

const form = document.querySelector('#note-form');
const textarea = document.querySelector('#note-text');
const saveButton = document.querySelector('#save-button');
const cancelButton = document.querySelector('#cancel-edit');
const list = document.querySelector('#note-list');
const template = document.querySelector('#note-template');
const emptyState = document.querySelector('#empty-state');
const countLabel = document.querySelector('#note-count');
const filterInput = document.querySelector('#filter');
const netStatus = document.querySelector('#net-status');

const DRAFT_KEY = 'pocket-notes:draft';
const dateFormat = new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' });

let notes = [];          // in-memory copy of the store, newest first
let editingId = null;    // id of the note being edited, or null when creating

// Tell other open tabs/windows to reload their list after a write.
const channel = 'BroadcastChannel' in self ? new BroadcastChannel('pocket-notes') : null;
channel?.addEventListener('message', (event) => {
  if (event.data === 'notes-changed') refresh();
});

// ---------- Rendering ----------

function render() {
  const query = filterInput.value.trim().toLowerCase();
  const visible = query ? notes.filter((n) => n.text.toLowerCase().includes(query)) : notes;

  // Build off-DOM, then swap in one operation.
  const fragment = document.createDocumentFragment();
  for (const note of visible) {
    const item = template.content.firstElementChild.cloneNode(true);
    item.dataset.id = note.id;
    item.classList.toggle('is-editing', note.id === editingId);
    item.querySelector('.note-text').textContent = note.text; // textContent: never parse user input as HTML
    const time = item.querySelector('.note-time');
    time.dateTime = new Date(note.updatedAt).toISOString();
    time.textContent = dateFormat.format(note.updatedAt);
    fragment.append(item);
  }
  list.replaceChildren(fragment);

  countLabel.textContent = notes.length ? `(${notes.length})` : '';
  emptyState.hidden = notes.length > 0;
}

async function refresh() {
  try {
    notes = await getAllNotes();
    render();
  } catch (error) {
    showError('Could not load notes', error);
  }
}

// ---------- Editing ----------

function startEditing(note) {
  editingId = note.id;
  textarea.value = note.text;
  saveButton.textContent = 'Update note';
  cancelButton.hidden = false;
  textarea.focus();
  render();
}

function stopEditing() {
  editingId = null;
  form.reset();
  saveButton.textContent = 'Save note';
  cancelButton.hidden = true;
  clearDraft();
  render();
}

async function saveCurrentNote() {
  const text = textarea.value.trim();
  if (!text) return;

  const now = Date.now();
  try {
    if (editingId) {
      const existing = await getNote(editingId);
      // The note may have been deleted in another tab meanwhile: recreate it.
      await putNote({ ...(existing ?? { id: editingId, createdAt: now }), text, updatedAt: now });
    } else {
      // crypto.randomUUID() requires a secure context, which a PWA always has.
      await putNote({ id: crypto.randomUUID(), text, createdAt: now, updatedAt: now });
    }
    stopEditing();
    await refresh();
    channel?.postMessage('notes-changed');
    requestPersistentStorage();
  } catch (error) {
    showError('Could not save the note', error);
  }
}

form.addEventListener('submit', (event) => {
  event.preventDefault();
  saveCurrentNote();
});

// Ctrl+Enter / Cmd+Enter saves from inside the textarea.
textarea.addEventListener('keydown', (event) => {
  if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) {
    event.preventDefault();
    saveCurrentNote();
  }
});

cancelButton.addEventListener('click', stopEditing);
filterInput.addEventListener('input', render);

// One delegated listener handles Edit/Delete for every note.
list.addEventListener('click', async (event) => {
  const button = event.target.closest('button[data-action]');
  if (!button) return;
  const id = button.closest('.note').dataset.id;
  const note = notes.find((n) => n.id === id);
  if (!note) return;

  if (button.dataset.action === 'edit') {
    startEditing(note);
  } else if (button.dataset.action === 'delete') {
    if (!confirm('Delete this note?')) return;
    try {
      await deleteNote(id);
      if (editingId === id) stopEditing();
      await refresh();
      channel?.postMessage('notes-changed');
    } catch (error) {
      showError('Could not delete the note', error);
    }
  }
});

// ---------- Draft autosave (survives the reload after an app update) ----------

function saveDraft() {
  try {
    sessionStorage.setItem(DRAFT_KEY, JSON.stringify({ text: textarea.value, editingId }));
  } catch { /* storage can be unavailable (e.g. blocked); drafts are best-effort */ }
}

function clearDraft() {
  try { sessionStorage.removeItem(DRAFT_KEY); } catch { /* ignore */ }
}

function restoreDraft() {
  try {
    const draft = JSON.parse(sessionStorage.getItem(DRAFT_KEY) ?? 'null');
    if (draft?.text) {
      textarea.value = draft.text;
      if (draft.editingId) {
        editingId = draft.editingId;
        saveButton.textContent = 'Update note';
        cancelButton.hidden = false;
      }
    }
  } catch { /* ignore malformed drafts */ }
}

textarea.addEventListener('input', saveDraft);

// ---------- Status, errors, storage ----------

function updateNetworkStatus() {
  // navigator.onLine === false is reliable; true only means "some network exists".
  netStatus.textContent = navigator.onLine ? '' : 'Offline';
}
window.addEventListener('online', updateNetworkStatus);
window.addEventListener('offline', updateNetworkStatus);

function showError(message, error) {
  console.error(`[app] ${message}:`, error);
  netStatus.textContent = `${message}.`;
}

let persistenceRequested = false;
async function requestPersistentStorage() {
  // Ask once, after the user has created data worth protecting from eviction.
  if (persistenceRequested || !navigator.storage?.persist) return;
  persistenceRequested = true;
  try {
    const persisted = (await navigator.storage.persisted()) || (await navigator.storage.persist());
    console.info(`[app] persistent storage: ${persisted ? 'granted' : 'not granted'}`);
  } catch (error) {
    console.warn('[app] storage.persist() failed:', error);
  }
}

// ---------- Launch handling ----------

function handleLaunchParams() {
  // The "New note" app shortcut launches ./?action=new&source=shortcut
  const url = new URL(location.href);
  if (url.searchParams.get('action') !== 'new') return;

  // Consume the parameter: location.reload() after an update keeps the URL, and
  // re-running the action would wipe the draft that restoreDraft() just brought back.
  url.searchParams.delete('action');
  history.replaceState(history.state, '', url);

  if (!textarea.value) stopEditing(); // never discard unsaved text
  textarea.focus();
}

// ---------- Boot ----------

// First, synchronously: beforeinstallprompt can fire right after the load event,
// so its listener must be attached before this module does any async work.
initPwa();
updateNetworkStatus();
restoreDraft();
refresh().then(handleLaunchParams);

app.js imports initPwa() from pwa.js, which you write in Step 9. A module graph fails as a whole if one import 404s, so create a stub now to try the app right away:

// app.js imports initPwa(), so this module must exist before Step 9.
export function initPwa() {}

Start the dev server with npm start (or npx serve public) and open http://localhost:3000. You can add, edit, filter and delete notes, and they survive a reload. The app doesn't work offline yet, and the browser doesn't offer to install it.

Rendering without a framework¶

render() rebuilds the list from the in-memory notes array on every change. It clones the <template> for each note, fills it with textContent (never innerHTML, so a note containing <img onerror=…> is displayed, not executed), collects the items in a DocumentFragment, and swaps them in with one replaceChildren() call. For a few hundred notes, that's comfortably fast. For thousands you'd add virtualization, which Runtime Performance discusses.

Edit and Delete use event delegation: one click listener on the <ul> finds the nearest button[data-action], so re-rendering never needs to re-attach listeners.

IDs, cross-tab sync and drafts¶

• crypto.randomUUID() generates collision-free IDs on the device, with no server round trip. It's available only in secure contexts, which a PWA always is.
• BroadcastChannel('pocket-notes') connects every same-origin window, tab and installed app window. After each write, the writer posts notes-changed and the other contexts re-read IndexedDB. A BroadcastChannel never delivers a message to the object that posted it, so the writer doesn't refresh twice.
• The draft in sessionStorage is saved on every keystroke. sessionStorage is per tab, synchronous and survives a reload of that tab, which is exactly the lifetime of the "new version available, reload?" flow in Step 9. It's gone when the tab closes, which is also right for an unsaved draft.

Asking for persistent storage¶

By default, browser storage is best-effort: under storage pressure, the browser may evict an origin's data without asking. navigator.storage.persist() asks for the persistent bucket mode, which is exempt from automatic eviction. app.js requests it once, after the first note is saved, because that's when there is something worth protecting and when the request makes sense to a user.

What happens next depends on the browser. According to MDN, Firefox shows a permission prompt, while Chromium-based browsers and Safari decide automatically, based on how the user has interacted with the site, and never prompt. In headless Chrome during testing, the request came back not granted; an installed app in a normal profile is a much stronger signal. Safari has a separate rule that matters even more: script-writable storage for a site with no user interaction in the last seven days of browser use can be deleted, unless the site was added to the Home Screen or the Dock. On iOS, installation is the storage-durability story. Storage Quotas & Persistence has the full per-browser quota and eviction rules.

Launch parameters and boot order¶

When the app starts from the New note shortcut, the URL is ./?action=new&source=shortcut. handleLaunchParams() reads action=new and focuses the editor. It then consumes the parameter with history.replaceState(). That matters because location.reload(), which the update flow in Step 9 uses, reloads the current URL: without the cleanup, a user who launched from the shortcut, typed a note and accepted an update would get the action a second time, and stopEditing() would clear the draft that restoreDraft() had just restored. For the same reason, the function only resets the editor when it is empty. The source parameters stay in the URL; they're for analytics, so you can tell launches from the home screen, a shortcut and a browser tab apart.

The last four lines matter more than they look. initPwa() runs first and synchronously attaches the beforeinstallprompt listener. Chromium can dispatch that event almost immediately after the load event: less than 10 ms later in repeated tests of this app on localhost. If the listener were attached after an await, it could miss the event, and the install button would never appear.

Step 6: Generate the icons, including maskable ones¶

An installable app needs more icons than a website: launcher icons at several densities, a separate maskable variant that platforms can crop into circles and squircles, an Apple touch icon, a favicon and a shortcut icon. Drawing them by hand invites mistakes, so this project keeps two vector sources and renders everything else from them.

Two sources: any and maskable¶

The any artwork is what most people picture as an app icon: a rounded tile with transparent corners. Browsers use it as-is in install dialogs, the Windows taskbar, the macOS Dock and ChromeOS shelf:

<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
  <!-- "any" icon: a rounded tile with transparent corners -->
  <rect width="512" height="512" rx="112" fill="#1f6f5c"/>
  <g id="glyph">
    <path d="M152 112h160l72 72v200a24 24 0 0 1-24 24H152a24 24 0 0 1-24-24V136a24 24 0 0 1 24-24z" fill="#f7f4ed"/>
    <path d="M312 112v48a24 24 0 0 0 24 24h48z" fill="#c9dcd5"/>
    <rect x="172" y="228" width="168" height="20" rx="10" fill="#1f6f5c"/>
    <rect x="172" y="280" width="168" height="20" rx="10" fill="#1f6f5c" opacity=".7"/>
    <rect x="172" y="332" width="112" height="20" rx="10" fill="#1f6f5c" opacity=".45"/>
  </g>
</svg>

The maskable artwork fills the whole square with the background color and shrinks the glyph by 10% so it fits in the safe zone:

<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
  <!-- Maskable icon: full-bleed background, artwork inside the 80% safe zone -->
  <rect width="512" height="512" fill="#1f6f5c"/>
  <g transform="translate(256 260) scale(0.9) translate(-256 -260)">
    <path d="M152 112h160l72 72v200a24 24 0 0 1-24 24H152a24 24 0 0 1-24-24V136a24 24 0 0 1 24-24z" fill="#f7f4ed"/>
    <path d="M312 112v48a24 24 0 0 0 24 24h48z" fill="#c9dcd5"/>
    <rect x="172" y="228" width="168" height="20" rx="10" fill="#1f6f5c"/>
    <rect x="172" y="280" width="168" height="20" rx="10" fill="#1f6f5c" opacity=".7"/>
    <rect x="172" y="332" width="112" height="20" rx="10" fill="#1f6f5c" opacity=".45"/>
  </g>
</svg>

The maskable safe zone, with the math¶

Android launchers and some other surfaces apply their own mask shape to icons marked purpose: "maskable": a circle on one device, a rounded square or a teardrop on another. The manifest specification defines the safe zone, the area guaranteed to survive any mask, as "a circle with center point in the center of the icon and with a radius of ⅖ (40%) of the icon size". Everything outside it may be cropped, and the user agent may also scale the icon.

For the 512 × 512 canvas, the safe zone is a circle of radius 204.8 px around (256, 256). The glyph's bounding box in source.svg runs from (128, 112) to (384, 408). After maskable.svg scales it by 0.9 around (256, 260), the box becomes (140.8, 126.8) to (371.2, 393.2). The farthest corners are 115.2 px across and 137.2 px down from the center, a distance of √(115.2² + 137.2²) ≈ 179.2 px. That's about 25 px inside the 204.8 px limit, so no mask can clip the page. The corner of the page glyph is the part to watch; round logos can be larger than square ones.

Keep the two variants as separate icon entries. A single image marked "purpose": "any maskable" can't be right in both roles: artwork padded for masking looks too small when used unmasked, and a tight any icon gets its corners cut off when masked. Chromium also requires at least one any icon for installability. A manifest with only maskable icons fails the check (see Installability Criteria).

Rendering the PNGs with sharp¶

// tools/make-icons.mjs — rasterize the two source SVGs into every PNG the app needs.
// Usage: npm run icons   (requires the sharp dev dependency)
import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
import sharp from 'sharp';

const SRC = new URL('../icon-src/', import.meta.url);
const OUT = new URL('../public/icons/', import.meta.url);

// [source SVG, output file, size in px, flatten onto an opaque background?]
const JOBS = [
  ['source.svg', 'favicon-32.png', 32, false],
  ['source.svg', 'icon-192.png', 192, false],
  ['source.svg', 'icon-512.png', 512, false],
  ['maskable.svg', 'maskable-192.png', 192, true],
  ['maskable.svg', 'maskable-512.png', 512, true],
  // iOS applies its own rounded mask and can render transparent pixels black: use full-bleed art.
  ['maskable.svg', 'apple-touch-icon.png', 180, true],
  ['maskable.svg', 'shortcut-new-96.png', 96, true],
];

await mkdir(OUT, { recursive: true });

for (const [source, output, size, opaque] of JOBS) {
  const svg = await readFile(new URL(source, SRC));
  // The SVGs are drawn on a 512x512 canvas, so every PNG is a downscale, never an upscale.
  let image = sharp(svg).resize(size, size);
  if (opaque) image = image.flatten({ background: '#1f6f5c' });
  await writeFile(new URL(output, OUT), await image.png({ compressionLevel: 9 }).toBuffer());
  console.log(`public/icons/${output}  ${size}x${size}`);
}

// Modern browsers can use the vector artwork directly as the tab icon.
await copyFile(new URL('source.svg', SRC), new URL('favicon.svg', OUT));
console.log('public/icons/favicon.svg  (copy of icon-src/source.svg)');

Run it once, and again whenever the artwork changes:

npm run icons

public/icons/favicon-32.png  32x32
public/icons/icon-192.png  192x192
public/icons/icon-512.png  512x512
public/icons/maskable-192.png  192x192
public/icons/maskable-512.png  512x512
public/icons/apple-touch-icon.png  180x180
public/icons/shortcut-new-96.png  96x96
public/icons/favicon.svg  (copy of icon-src/source.svg)

The maskable and Apple icons are flattened onto the brand color, which removes the alpha channel entirely. iOS applies its own rounded mask to touch icons and can render transparent pixels as black, and a maskable icon with transparent edges shows whatever the launcher puts behind it.

Screenshots for the richer install dialog¶

The manifest in the next step also lists two screenshots. Chrome shows them, with the manifest description, in a richer install dialog: a bottom sheet on Android (since Chrome 94) and a larger dialog on desktop (since Chrome 108), according to Chrome's announcement. Chromium only accepts screenshots between 320 and 3840 pixels on each side whose long side is at most 2.3 times the short side, as the Rich Install UI page details.

Capture them from the running app once it has some notes in it. In Chrome DevTools, open the device toolbar (Ctrl+Shift+M or Cmd+Shift+M), set a responsive size of 1280 × 800 at device pixel ratio 1, open the Command Menu (Ctrl+Shift+P or Cmd+Shift+P) and run Capture screenshot. Save it as public/screenshots/wide.png. Repeat at 375 × 667 with a device pixel ratio of 2 to get a 750 × 1334 image for narrow.png. Both have ratios well under 2.3 (1.6 and 1.78).

Step 7: Write the web app manifest¶

The manifest is a JSON file that tells the browser how the installed app should look and behave: its identity, name, icons, start page, window style and colors.

{
  "id": "/",
  "name": "Pocket Notes",
  "short_name": "Notes",
  "description": "Offline-first notes that live on your device. Works without a connection and installs like an app.",
  "lang": "en",
  "dir": "ltr",
  "start_url": "./?source=pwa",
  "scope": "./",
  "display": "standalone",
  "background_color": "#f7f4ed",
  "theme_color": "#1f6f5c",
  "categories": ["productivity", "utilities"],
  "icons": [
    { "src": "icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
    { "src": "icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
    { "src": "icons/maskable-192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
    { "src": "icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ],
  "screenshots": [
    {
      "src": "screenshots/wide.png",
      "sizes": "1280x800",
      "type": "image/png",
      "form_factor": "wide",
      "label": "Pocket Notes on a desktop: the editor above a list of saved notes"
    },
    {
      "src": "screenshots/narrow.png",
      "sizes": "750x1334",
      "type": "image/png",
      "form_factor": "narrow",
      "label": "Pocket Notes on a phone: writing a note while offline"
    }
  ],
  "shortcuts": [
    {
      "name": "New note",
      "short_name": "New",
      "description": "Start writing a new note",
      "url": "./?action=new&source=shortcut",
      "icons": [{ "src": "icons/shortcut-new-96.png", "sizes": "96x96", "type": "image/png" }]
    }
  ]
}

JSON allows no comments and no trailing commas. A single stray comma makes the whole manifest fail to parse, and Chromium reports manifest-parsing-or-network-error rather than pointing at the line. Validate the file with python3 -m json.tool public/manifest.webmanifest or your editor before debugging anything else.

Member by member¶

Support for these members varies. According to MDN's compatibility data, shortcuts works in Chrome and Edge (96 on desktop, 84 on Android) and Safari 17.4 on macOS, but not on iOS. Safari on iOS reads id (16.4), name, start_url, scope and display, uses theme_color from iOS 15, and ignores background_color. The full matrix is in the Members Reference and the Manifest Cheat Sheet. App Identity & Updates explains how browsers apply manifest changes to apps that are already installed.

The .webmanifest extension is the one the specification registers, with the MIME type application/manifest+json. Chromium doesn't reject other JSON types, but serve the right one anyway: Step 13 shows how, including for the servers whose default MIME tables don't know the extension.

If you reload the app now, Chrome and Edge may already show the install icon in the address bar. Chromium no longer requires a service worker for that. Without one, though, an installed Pocket Notes would show Chrome's generic offline page as soon as the network drops. The next step fixes that.

Step 8: Write the service worker¶

The service worker is a script that runs in its own thread, outside any page, and acts as a programmable proxy between the app and the network. Pocket Notes' worker is about 150 lines of plain JavaScript:

/* sw.js — Pocket Notes service worker (classic script, scope "./").
 *
 * Bump VERSION whenever any file in APP_SHELL changes. The byte change in this
 * file is what makes the browser install the new worker and re-download the shell.
 */
const VERSION = 'v1.0.0';
const CACHE_PREFIX = 'pocket-notes-';
const PRECACHE = `${CACHE_PREFIX}precache-${VERSION}`;
const RUNTIME = `${CACHE_PREFIX}runtime`; // unversioned: survives app updates
const RUNTIME_MAX_ENTRIES = 50;

// Everything the app needs to start with no network. Paths resolve against this file's URL.
const APP_SHELL = [
  './',
  './index.html',
  './offline.html',
  './styles.css',
  './app.js',
  './db.js',
  './pwa.js',
  './manifest.webmanifest',
  './icons/favicon.svg',
  './icons/favicon-32.png',
  './icons/icon-192.png',
  './icons/icon-512.png',
  './icons/maskable-192.png',
  './icons/maskable-512.png',
  './icons/apple-touch-icon.png',
];

// ---------------------------------------------------------------------------
// install: download the whole app shell into a new, versioned cache
// ---------------------------------------------------------------------------
self.addEventListener('install', (event) => {
  event.waitUntil(
    (async () => {
      const cache = await caches.open(PRECACHE);
      // cache: 'reload' bypasses the HTTP cache so a stale copy is never precached.
      // addAll() is atomic: if any request fails, nothing is stored and install fails.
      await cache.addAll(APP_SHELL.map((url) => new Request(url, { cache: 'reload' })));
    })(),
  );
  // No skipWaiting() here: an update waits until the user accepts the "new version" toast.
});

// ---------------------------------------------------------------------------
// activate: delete caches from older versions, then control open pages
// ---------------------------------------------------------------------------
self.addEventListener('activate', (event) => {
  event.waitUntil(
    (async () => {
      const keep = new Set([PRECACHE, RUNTIME]);
      const names = await caches.keys();
      await Promise.all(
        names
          .filter((name) => name.startsWith(CACHE_PREFIX) && !keep.has(name))
          .map((name) => caches.delete(name)),
      );
      // Take control of pages that loaded before this worker existed (the first visit).
      await self.clients.claim();
    })(),
  );
});

// ---------------------------------------------------------------------------
// message: the page asks the waiting worker to activate
// ---------------------------------------------------------------------------
self.addEventListener('message', (event) => {
  if (event.data?.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

// ---------------------------------------------------------------------------
// fetch: route requests
// ---------------------------------------------------------------------------
self.addEventListener('fetch', (event) => {
  const { request } = event;

  // Only handle same-origin GET requests; everything else goes to the network untouched.
  if (request.method !== 'GET') return;
  const url = new URL(request.url);
  if (url.origin !== self.location.origin) return;

  if (request.mode === 'navigate') {
    event.respondWith(handleNavigation(request));
  } else {
    event.respondWith(handleAsset(event));
  }
});

/** Page loads: app shell from the precache, other pages network-first, offline page last. */
async function handleNavigation(request) {
  // ignoreSearch: the start_url (./?source=pwa) and shortcut URLs (./?action=new)
  // must all map to the precached "./" entry.
  const cached = await caches.match(request, { cacheName: PRECACHE, ignoreSearch: true });
  if (cached) return stripRedirect(cached);

  try {
    return await fetch(request);
  } catch {
    const fallback = await caches.match('./offline.html', { cacheName: PRECACHE });
    return fallback ? stripRedirect(fallback) : Response.error();
  }
}

/** Subresources: precache first, then stale-while-revalidate for everything else. */
async function handleAsset(event) {
  const { request } = event;

  const precached = await caches.match(request, { cacheName: PRECACHE });
  if (precached) return precached;

  const cache = await caches.open(RUNTIME);
  const cached = await cache.match(request);

  const fromNetwork = fetch(request).then((response) => {
    // Only cache complete, successful same-origin responses (never 206 partials or errors).
    if (response.status === 200) {
      const copy = response.clone();
      event.waitUntil(cache.put(request, copy).then(() => trimCache(cache, RUNTIME_MAX_ENTRIES)));
    }
    return response;
  });

  if (cached) {
    // Serve the cached copy now; refresh it in the background.
    event.waitUntil(fromNetwork.catch(() => {}));
    return cached;
  }
  return fromNetwork; // offline + not cached: rejects, and the request fails as it would without a SW
}

/**
 * Navigations use redirect mode "manual". Answering one with a response that was
 * itself the result of a redirect makes the navigation fail, so copy such responses
 * into a fresh, non-redirected Response.
 */
async function stripRedirect(response) {
  if (!response.redirected) return response;
  const body = await response.blob();
  return new Response(body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
}

/** Deletes the oldest entries (cache.keys() returns insertion order) beyond maxEntries. */
async function trimCache(cache, maxEntries) {
  const keys = await cache.keys();
  const excess = keys.length - maxEntries;
  if (excess > 0) {
    await Promise.all(keys.slice(0, excess).map((key) => cache.delete(key)));
  }
}