New to Rust? Grab our free Rust for Beginners eBook Get it free →
How to Build a Progressive Web App from Scratch

Turning a website into an installable app also means deciding what it can show when the network is unavailable. A progressive web app, or PWA, is a website that uses browser features for installation and to handle requests when the network is down.
This walkthrough shows how to build a web app step by step and check its offline behavior before shipping.
TL;DR
A progressive web app starts as a regular website, then adds a manifest for installation and a service worker for controlled offline behavior. Build the page first, serve it from localhost or HTTPS, and make the cached experience match what the app can safely do without a network.
- Create a responsive HTML app and link a web app manifest.
- Register a service worker from the app’s origin and cache its shell.
- Test installation and offline behavior in browser developer tools.
What Is a Progressive Web App?
A progressive web app uses browser features to offer app-like behavior while remaining accessible at a web address.
A service worker intercepts requests and can return cached responses. Installation and offline behavior are configured separately.
A calculator can remain useful with its interface cached.
How to Build a Progressive Web App Step by Step
Build the normal web page before adding browser features so the site remains useful without installation.
Step 1: Create the web app shell
Create a project with an HTML page, stylesheet, JavaScript file, manifest and service worker. Check the registered scope in developer tools.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#17324d">
<link rel="manifest" href="/manifest.webmanifest">
<link rel="stylesheet" href="/style.css">
<title>Field Notes</title>
</head>
<body>
<main>
<h1>Field Notes</h1>
<p>Your saved notes appear here.</p>
</main>
<script src="/app.js" defer></script>
</body>
</html>
The page links its manifest and stylesheet, then loads the app script after parsing. This sample has no remote data, so its cached shell can reopen as shown.
Step 2: Add the web app manifest
Create manifest.webmanifest as JSON and point its icon paths to image files in your project.
Use existing icons with matching dimensions. Chromium checks required manifest fields during its install flow.
Inspect parsed fields in the Application or Manifest panel when install options are missing.
Step 3: Register a service worker
Register the worker with a URL on the same origin as the page, and use feature detection so browsers without the API continue to serve the site as a regular web page. Handle a rejected promise so path or security errors show during development.
if ("serviceWorker" in navigator) {
window.addEventListener("load", () => {
navigator.serviceWorker.register("/sw.js")
.catch((error) => console.error("Service worker registration failed", error));
});
}
Serve the page locally rather than opening it from disk. A worker under /assets/ normally controls only that directory unless the server sends an appropriate Service-Worker-Allowed header, so this example keeps sw.js at the site root.
The browser installs the worker, then activates it after the old worker stops controlling open pages.
Reload and inspect navigator.serviceWorker.controller to confirm control.
Serve the project from one consistent localhost port during development because the port is part of the origin.
Step 4: Cache the app shell and handle requests
Use an explicit cache name and wait for essential files during installation. If a required file fails to cache, installation should fail rather than leave a worker that promises an incomplete offline screen.
const CACHE = "field-notes-v1";
const SHELL = ["/", "/index.html", "/style.css", "/app.js"];
self.addEventListener("install", (event) => {
event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(SHELL)));
});
self.addEventListener("activate", (event) => {
event.waitUntil(
caches.keys().then((keys) => Promise.all(
keys.filter((key) => key !== CACHE).map((key) => caches.delete(key))
))
);
});
self.addEventListener("fetch", (event) => {
const request = event.request;
const url = new URL(request.url);
if (request.method !== "GET" || url.origin !== self.location.origin) return;
if (request.mode === "navigate") {
event.respondWith(fetch(request).catch(() => caches.match("/index.html")));
return;
}
event.respondWith(
caches.match(request).then((cached) => cached || fetch(request))
);
});
Navigation tries the network first and returns the cached page after a failed request. Other same-origin GET files use cache-first behavior. This starter skips cross-origin requests.
Step 5: Test locally and deploy over HTTPS
Start a development server from the project directory, then open its localhost address in a browser. Confirm that the manifest parses and the service worker reaches an activated state in developer tools. Test a page reload with the browser’s offline mode enabled, then switch back online and reload again.
This sample can use static hosting, or a Node.js app can serve its assets. CodeForGeek’s guide to serving static files with Nginx and Node.js covers one deployment route.
The first visit must reach the server to download and install the worker and its cache.
What Should You Check Before Shipping a PWA?
Browser support and cache policy affect installation, offline behavior and updates. Check the following failure cases before describing the app as ready.
| Symptom | Likely cause | Check or fix |
|---|---|---|
| Worker registration rejects | HTTP outside localhost, wrong file path, or scope mismatch | Use HTTPS or localhost and inspect the worker URL and scope |
| Install option is missing | Manifest error or browser/platform behavior | Inspect manifest fields and use the browser’s supported install flow |
| Old files keep appearing | Existing worker or cache version remains active | Change the cache version and inspect waiting workers before deleting caches |
| Page opens offline but data is stale | Cached content is being treated as authoritative | Show connection state and define freshness for each data type |
| Offline page is blank | Navigation fallback or shell file was not cached | Confirm install completed and the fallback path exists in the cache |
For data that must survive a reload, choose a durable store and define conflict handling and sync status before adding queued writes.
A changed worker may wait while tabs use the old version, so give each release a cache name and remove only caches owned by this app.
Installation controls depend on the browser and platform. On iOS, use Safari’s Add to Home Screen flow.
Other browsers may offer an install prompt or menu item. Keep the site usable in a tab when no install option appears.
Keep authentication and authorization on the server. Avoid storing sensitive responses on shared devices.
CodeForGeek’s article on HTML5 desktop notifications covers a separate browser capability with its own permission and support requirements.
Guides: Choose an Offline Strategy for Each Request
Use the table to choose a cache rule by request type, rather than applying one policy to every response.
| Request | Policy to consider |
|---|---|
| Versioned assets | Serve the saved response from cache. |
| Navigation | Try the network, then use a cached page as fallback. |
| Feeds and mutations | Define freshness and offline handling separately. |
Tutorials: Add Offline Data Without Losing User Work
Offline forms need a queue and a clear promise to the user. Save a draft locally, then send it when a connection returns and show whether the server accepted it.
- Give each queued operation a stable client-generated identifier.
- Store pending work in IndexedDB so it survives reloads.
- Retry only operations the server can safely deduplicate and show pending or failed status.
- Define what happens if another device changed the same record.
Label queued work as saved on this device until the server confirms acceptance. For sensitive data, decide whether local storage is appropriate on shared devices and provide a way to clear it.
Reference: What the Manifest Fields Control
Check name, start_url, scope, display and icon paths against the files the server actually serves.
Link the JSON manifest with rel=”manifest” and test the supported installation flow on your target platforms.
| Field | What to verify |
|---|---|
| name and short_name | Readable app labels |
| start_url and scope | Launch path and pages included |
| display and theme_color | Window presentation and browser theme |
| icons | Files exist at declared paths and dimensions |
See Also: Deployment and Browser Capabilities
A reverse proxy must preserve the manifest, icon and worker paths and their content types.
For a Node.js deployment, CodeForGeek’s guide to serving static files with Nginx and Node.js covers a related hosting task. The site’s HTML5 desktop notification guide covers another browser feature, but notifications are separate from installability and offline caching.
- Confirm manifest, icons and worker load at their declared paths.
- Test installation and offline fallback on supported browsers.
Before calling the app ready, clear the browser’s old site data in a test profile, visit once online, reload, then test offline navigation and asset loading. Restore connectivity and confirm that the page updates without losing locally saved work. This sequence checks both first-visit setup and later use without confusing a warmed cache with a fresh installation.
Conclusion: Build the Web App Before Its Offline Layer
A PWA combines a web app with browser capabilities. Begin with a working page, connect its manifest, then add a service worker for network behavior you can explain and test. Read MDN’s PWA installability guide and service worker guide when you need platform details.
FAQ
These answers cover setup and browser behavior.
What is a progressive web app?
A progressive web app is a website enhanced with browser features such as an app manifest and, when needed, a service worker for controlled network behavior. It remains accessible as a website.
Does a PWA need a service worker to be installable?
No. A service worker can provide offline behavior, but installability and service-worker caching are separate capabilities. Browser installation criteria vary by platform.
Can a progressive web app work offline?
It can serve cached pages and assets when its service worker and cache strategy support that behavior. Server-backed data and actions still need an explicit offline design.
Can I test a PWA without HTTPS?
Browsers treat localhost as a secure development context for service workers. A deployed app should use HTTPS.




