PWA Tutorial

5.4. PWA Tutorial#

In this tutorial we will work step-by-step to build a To-Do list PWA using a Flask backend.

At the end of the tutorial you will have built a PWA that:

works like a website and can be used normally in a browser
can be installed as a local app
works online and offline, with to-do items synchronised on reconnection to the server

Note

While one of the key principles of a PWA is a responsive design, we will ignore the design and styling of the PWA in order to keep the code as simple as possible.

5.4.1. Setup#

To begin, let’s take a look at the overall structure of the project below

Directory structure#

my-todo-app/
│
├── app.py
├── static/
│   └── js/
│       └── app.js
└── templates/
    └── index.html

Explanation:

app.py contains Flask code responsible for the back end
static will contain static files such as the JavaScript in app.js responsible for the front end
templates contains the template file index.html

Backend#

The backend code in app.py performs the following:

Create an sqlite database called tasks.db if it doesn’t exist
Define a Task model using SQLAlchemy’s ORM
Setup routes for:
1. The homepage, which just renders the homepage template
2. GET-ing the list of all tasks in the database
3. POST-ing a new task to add to the database

app.py#

from flask import Flask, render_template, request, jsonify
from flask_sqlalchemy import SQLAlchemy
import os

app = Flask(__name__)

# -------------------------------------------------------
# Database configuration
# -------------------------------------------------------
app.config["SQLALCHEMY_DATABASE_URI"]  = f"sqlite:///tasks.db"
db = SQLAlchemy(app)

# Define the Task Model
class Task(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    text = db.Column(db.String(255), nullable=False)

    def to_dict(self):
        return {
            "id": self.id,
            "text": self.text
        }

# Create the database if it doesn't exist
with app.app_context():
    db.create_all()

# -------------------------------------------------------
# Routes
# -------------------------------------------------------
@app.route("/")
def home():
    """Serve the index page (homepage)"""
    return render_template("index.html")

@app.route("/api/tasks", methods=["GET"])
def get_tasks():
    """Return all tasks as JSON."""
    tasks = Task.query.all()
    return jsonify([task.to_dict() for task in tasks]), 200


@app.route("/api/tasks", methods=["POST"])
def create_task():
    """Create a new task."""
    data = request.get_json()
    if not data or "text" not in data:
        return jsonify({"error": "Invalid data"}), 400

    new_task = Task(text=data["text"])
    db.session.add(new_task)
    db.session.commit()
    return jsonify(new_task.to_dict()), 201

@app.route("/api/tasks/<int:task_id>", methods=["DELETE"])
def delete_task(task_id):
    """Delete an existing task."""
    task = Task.query.get(task_id)
    if not task:
        return jsonify({"error": "Task not found"}), 404

    db.session.delete(task)
    db.session.commit()
    return jsonify({"message": f"Task {task_id} deleted"}), 200

# -------------------------------------------------------
# Run the app
# -------------------------------------------------------
app.run(debug=True, reloader_type='stat', port=5000)

Frontend#

The frontend is composed of two files:

The index.html template which launches the controlling app.js code and has user interface placeholders
The app.js JavaScript that controls the webpage contents and connects to the backend

index.html

In the index.html template shown below:

A small form is presented to enter short to-do items
A placeholder <ul> is created which will be updated by the JavaScript code
The app.js script is loaded, which controls the web page

index.html#

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>PWA To-Do List</title>
</head>
<body>
  <h1>My PWA To-Do List</h1>
  
  <!-- Input row -->
  <div class="input-group">
    <input type="text" id="taskInput" placeholder="Enter a new task" />
    <button id="addTaskBtn">Add Task</button>
  </div>
  
  <!-- Task list, controlled by app.js -->
  <ul id="todoList"></ul>

  <!-- Main app logic -->
  <script src="/static/js/app.js"></script>
</body>
</html>

app.js

The app.js file is responsible for:

retrieving the list of tasks from the server and populating the <ul> on the first page load
responding to events such as creating a task or deleting a task

app.js#

// DOM Elements
const taskInput = document.getElementById("taskInput");
const addTaskBtn = document.getElementById("addTaskBtn");
const todoList = document.getElementById("todoList");

// Fetch tasks from the server and render them
async function fetchTasks() {
  try {
    const response = await fetch("/api/tasks");
    if (!response.ok) {
      throw new Error("Failed to fetch tasks");
    }
    const tasks = await response.json();
    renderTasks(tasks);
  } catch (error) {
    console.error(error);
  }
}

// Render tasks onto the page
function renderTasks(tasks) {
  todoList.innerHTML = "";
  tasks.forEach((task) => {
    const li = document.createElement("li");

    // Task text
    const span = document.createElement("span");
    span.textContent = task.text;
    li.appendChild(span);

    // Delete button
    const delBtn = document.createElement("button");
    delBtn.className = "delete-btn";
    delBtn.textContent = "X";
    delBtn.addEventListener("click", () => {
      deleteTask(task.id);
    });

    li.appendChild(delBtn);
    todoList.appendChild(li);
  });
}

// Create a new task (send to server)
async function createTask() {
  const newTaskText = taskInput.value.trim();
  if (!newTaskText) return;

  try {
    const response = await fetch("/api/tasks", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: newTaskText }),
    });

    if (!response.ok) {
      throw new Error("Failed to create task");
    }

    const createdTask = await response.json();
    // Re-fetch tasks to update the list
    await fetchTasks();
    // Clear input
    taskInput.value = "";
  } catch (error) {
    console.error(error);
  }
}

// Delete a task by ID
async function deleteTask(taskId) {
  try {
    const response = await fetch(`/api/tasks/${taskId}`, {
      method: "DELETE",
    });
    if (!response.ok) {
      throw new Error("Failed to delete task");
    }
    await fetchTasks(); // Re-fetch tasks to update the list
  } catch (error) {
    console.error(error);
  }
}

// Event Listeners
addTaskBtn.addEventListener("click", createTask);
taskInput.addEventListener("keyup", (e) => {
  if (e.key === "Enter") {
    createTask();
  }
});

// Initial fetch to populate the task list
fetchTasks();

5.4.2. Installable PWA#

So far we’ve created fairly standard website. To make it installable as a PWA we need to add the following:

The manifest (manifest.json), describing the PWA
An icon for installed application

The new project structure is below

Directory structure#

my-todo-app/
│
├── app.py
├── static/
│   ├── images/
│   │   └── icon-512.png
│   ├── js/
│   │   └── app.js
│   └── manifest.json
└── templates/
    └── index.html

Manifest#

The manifest provides some basic information to the web browser and operating system about how the PWA should be installed and presented to the user.

You’ll notice:

The manifest.json file is located under /static
The manifest is referenced in the index.html template so that the browser knows that the app is a PWA.

manifest.json#

{
  "name": "PWA To-Do List",
  "short_name": "ToDo",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0d6efd",
  "icons": [
    {
      "src": "/static/images/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Excerpt of index.html#

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>PWA To-Do List</title>
  
  <!-- Link to manifest -->
  <link rel="manifest" href="/static/manifest.json"/>
</head>

Icon#

You need to provide an icon to make the PWA installable. Below you can find the included icon at 512x512 size, feel free to change the icon to your liking.

The included app icon.#

5.4.3. Working Offline#

To make the app “progressive” by working when offline (disconnected from the web or the server), we need to:

Write a service worker, which
- intercepts network requests
- manages offline behaviour
Serve the service-worker.js file from the root of the URL, which allows it to intercept network requests
Add code to app.js to notify the service worker when the computer connects to the internet so that offline changes can be synchronised.
Update the index.html template to register the service worker

Note

Once you’re done working through the steps below, you can run the PWA and test the offline behaviour using the developer tools in your browser.

For example in Google Chrome under the “Application > Service workers” developer options you can tick “Offline” at the top of the page to put the window or tab into offline mode. Unticking the option restores the connection.

The new project structure is below

Directory structure#

my-todo-app/
│
├── app.py
├── static/
│   ├── images/
│   │   └── icon-512.png
│   ├── js/
│   │   ├── app.js
│   │   └── service-worker.js
│   └── manifest.json
└── templates/
    └── index.html

Service Worker#

The service worker definition is quite long as it handles the complex task of managing offline behaviour.

To summarise the service worker:

Caches files to make them available offline
Create an in-browser database to:
- Manage a copy of the task list so that the tasks are available offline
- Keep a copy of requests that happened offline so that they can be replayed to the server when reconnected
Intercept network requests
- Attempt to send the requests normally
- If the request fails because the computer is offline, store the requests to be replayed later
Listen for messages from app.js (main thread) that the computer has connected to the internet

service-worker.js#

// -------------------------------
// CONFIG
// -------------------------------
const CACHE_NAME = "todo-pwa-v2";
const STATIC_FILES = [
  "/", // root page
  "/static/js/app.js",
  "/static/manifest.json",
  // Add your CSS, icons, or other files here
];

// The name/version of our IndexedDB
const DB_NAME = "todo_db";
const DB_VERSION = 2; // bump if you add new stores or changes

// -------------------------------
// 1. INSTALL & CACHE STATIC ASSETS
// -------------------------------
self.addEventListener("install", (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(STATIC_FILES)),
  );
  // Force the waiting service worker to become the active service worker
  self.skipWaiting();
});

// -------------------------------
// 2. ACTIVATE & CLEAN OLD CACHES
// -------------------------------
self.addEventListener("activate", (event) => {
  event.waitUntil(
    (async () => {
      // Delete older caches
      const keys = await caches.keys();
      await Promise.all(
        keys.map((key) => {
          if (key !== CACHE_NAME) {
            return caches.delete(key);
          }
        }),
      );
      // Take control of all pages
      self.clients.claim();

      // Attempt to replay offline requests if any exist
      await replayRequests();
    })(),
  );
});

// -------------------------------
// 3. INDEXEDDB SETUP
//    - "tasks" store holds actual tasks { id, text }
//    - "requests" store queues offline POST/DELETE ops
// -------------------------------
let dbPromise = null;

/**
 * Open (or create) the IndexedDB with "tasks" and "requests" stores.
 */
function initDB() {
  if (!dbPromise) {
    dbPromise = new Promise((resolve, reject) => {
      const request = indexedDB.open(DB_NAME, DB_VERSION);

      request.onupgradeneeded = (e) => {
        const db = e.target.result;

        // 1. tasks store: keyPath = "id"
        if (!db.objectStoreNames.contains("tasks")) {
          db.createObjectStore("tasks", { keyPath: "id" });
        }

        // 2. requests store: keyPath = "id" (autoIncrement for queued ops)
        if (!db.objectStoreNames.contains("requests")) {
          db.createObjectStore("requests", {
            keyPath: "id",
            autoIncrement: true,
          });
        }
      };

      request.onsuccess = (e) => {
        resolve(e.target.result);
      };
      request.onerror = (e) => reject(e.target.error);
    });
  }
  return dbPromise;
}

// -------------------------------
// 4. STORING & RETRIEVING TASKS OFFLINE
// -------------------------------
async function storeTasksOffline(tasks) {
  const db = await initDB();
  const tx = db.transaction("tasks", "readwrite");
  const store = tx.objectStore("tasks");
  // Clear existing tasks
  await store.clear();
  // Insert/update each task
  for (const task of tasks) {
    await store.put(task);
  }
  await tx.done;
}

function getTasksOffline() {
  return new Promise((resolve, reject) => {
    initDB()
      .then((db) => {
        const tx = db.transaction("tasks", "readonly");
        const store = tx.objectStore("tasks");
        const req = store.getAll();
        req.onsuccess = () => resolve(req.result);
        req.onerror = () => reject(req.error);
      })
      .catch(reject);
  });
}

// -------------------------------
// 5. STORING & REPLAYING OFFLINE REQUESTS
// -------------------------------
async function queueRequest(method, url, body) {
  const db = await initDB();
  const tx = db.transaction("requests", "readwrite");
  const store = tx.objectStore("requests");
  await store.add({ method, url, body, timestamp: Date.now() });
  await tx.done;
}

// Retrieve all queued requests
function getAllRequests() {
  return new Promise((resolve, reject) => {
    initDB()
      .then((db) => {
        const tx = db.transaction("requests", "readonly");
        const store = tx.objectStore("requests");
        const req = store.getAll();
        req.onsuccess = () => resolve(req.result);
        req.onerror = () => reject(req.error);
      })
      .catch(reject);
  });
}

// Remove a request from the queue once replayed
async function removeRequest(id) {
  const db = await initDB();
  const tx = db.transaction("requests", "readwrite");
  const store = tx.objectStore("requests");
  await store.delete(id);
  await tx.done;
}

// Replay queued offline ops
async function replayRequests() {
  const allRequests = await getAllRequests();
  if (!allRequests.length) return;

  for (const req of allRequests) {
    try {
      if (req.method === "POST") {
        // Attempt to POST to the server
        const res = await fetch(req.url, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(req.body),
        });
        if (!res.ok) throw new Error("POST replay failed");
      } else if (req.method === "DELETE") {
        // Attempt to DELETE from the server
        const res = await fetch(req.url, { method: "DELETE" });
        if (!res.ok) throw new Error("DELETE replay failed");
      }
      // If successful, remove from queue
      await removeRequest(req.id);
    } catch (err) {
      console.error("[SW] Replay failed:", err);
      // If it fails again, we'll keep it in the queue
    }
  }

  // Now that we've replayed ops, let's re-fetch tasks from the server to refresh local store
  try {
    const response = await fetch("/api/tasks");
    if (response.ok) {
      const tasks = await response.json();
      await storeTasksOffline(tasks);
    }
  } catch (err) {
    console.warn("[SW] Could not refresh tasks after replay:", err);
  }
}

async function addTaskToLocalStore(task) {
  const db = await initDB();
  const tx = db.transaction("tasks", "readwrite");
  const store = tx.objectStore("tasks");
  await store.put(task); // Put/Update this single task
  await tx.done;
}

async function removeTaskFromLocalStore(id) {
  const db = await initDB();
  const tx = db.transaction("tasks", "readwrite");
  const store = tx.objectStore("tasks");
  await store.delete(id);
  await tx.done;
}

// -------------------------------
// 6. FETCH EVENT INTERCEPTION
// -------------------------------
self.addEventListener("fetch", (event) => {
  const { request } = event;

  // Only handle same-origin requests
  if (!request.url.startsWith(self.location.origin)) {
    return; // Skip cross-origin
  }

  // If not /api/tasks, do a cache-first approach for static files
  if (!request.url.includes("/api/tasks")) {
    event.respondWith(
      caches.match(request).then((cachedResponse) => {
        return cachedResponse || fetch(request);
      }),
    );
    return;
  }

  // Handle /api/tasks logic
  if (request.method === "GET") {
    // Network-first for GET /api/tasks
    event.respondWith(
      (async () => {
        try {
          // 1. Try network
          const networkResponse = await fetch(request);
          // 2. If successful, store tasks offline
          const cloned = networkResponse.clone();
          const tasks = await cloned.json();
          await storeTasksOffline(tasks);
          // 3. Return real network response
          return networkResponse;
        } catch (err) {
          console.warn(
            "[SW] GET /api/tasks offline, returning local tasks:",
            err,
          );
          // 4. If offline, return tasks from IndexedDB
          const offlineTasks = await getTasksOffline();
          return new Response(JSON.stringify(offlineTasks), {
            headers: { "Content-Type": "application/json" },
          });
        }
      })(),
    );
  } else if (request.method === "POST") {
    event.respondWith(
      (async () => {
        const clonedRequest = request.clone();
        try {
          // Attempt network
          const networkResponse = await fetch(request);
          return networkResponse;
        } catch (err) {
          console.warn("[SW] Offline, queueing POST request:", err);

          // Read the body from the cloned request
          const taskData = await clonedRequest.json();
          // e.g. { text: "Buy milk" }

          // Generate a LARGE placeholder ID so it sorts at the bottom
          // This ID is guaranteed bigger than typical server IDs.
          const offlineId = 10_000_000_000_000 + Date.now();
          // or something similarly large

          // Create an offline placeholder task
          const offlineTask = {
            id: offlineId,
            text: taskData.text,
            offline: true, // optional flag to mark it as offline
          };

          // Store this task in the "tasks" object store so it appears in offline data
          await addTaskToLocalStore(offlineTask);

          // Queue the original request for replay
          await queueRequest("POST", request.url, taskData);

          // Return a fake 201 so the front-end thinks creation succeeded
          // Optionally return some minimal JSON that matches a server response
          return new Response(
            JSON.stringify({
              message: "Offline creation success",
              id: offlineId,
            }),
            { status: 201, headers: { "Content-Type": "application/json" } },
          );
        }
      })(),
    );
  } else if (request.method === "DELETE") {
    event.respondWith(
      (async () => {
        const requestClone = request.clone();
        try {
          const networkResponse = await fetch(request);
          return networkResponse;
        } catch (err) {
          console.warn("[SW] Offline, queueing DELETE request:", err);

          // 1. Parse the task ID from the URL or request
          // e.g., /api/tasks/123
          const urlParts = requestClone.url.split("/");
          const taskIdStr = urlParts[urlParts.length - 1];
          const taskId = Number(taskIdStr);

          // 2. Remove from local 'tasks' store immediately
          if (!isNaN(taskId)) {
            await removeTaskFromLocalStore(taskId);
          }

          // 3. Queue the request so it replays later
          await queueRequest("DELETE", requestClone.url, null);

          // 4. Return a fake success
          return new Response(JSON.stringify({ message: "Deleted offline." }), {
            status: 200,
            headers: { "Content-Type": "application/json" },
          });
        }
      })(),
    );
  }
});

// -------------------------------
// 7. SYNC WHEN ONLINE AGAIN
// -------------------------------
self.addEventListener("message", (event) => {
  if (event.data && event.data.type === "ONLINE") {
    console.log("[SW] Received message to replay requests");
    event.waitUntil(replayRequests());
  }
});

Serving the Service Worker#

Part of the security restrictions of service workers is that they can only listen for network requests made to the same path, or descendants of the path, that they are served from. This means we need to serve the service-worker.js file from /service-worker.js to intercept all network requests made to the server.

By using Flask’s send_from_directory we can add a new view to serve the file at the root path.

app.py#

@app.route("/service-worker.js")
def service_worker():
    # Make sure the correct MIME type is used for the service worker.
    return send_from_directory("static/js", "service-worker.js")

Online Event#

When the browser detects online/offline conditions it broadcasts these to any listening objects. We can pass these events on to the service worker through the inbuilt messaging system that allows the main browser thread and service workers to communicate.

Adding the code below to app.js achieves this task:

app.js#

window.addEventListener("online", () => {
  if (navigator.serviceWorker && navigator.serviceWorker.controller) {
    navigator.serviceWorker.controller.postMessage({ type: "ONLINE" });
  }
});

Register Service Worker#

To finally register the service worker you can add the small snippet of JavaScript shown below to index.html.

index.html#

  <!-- Register Service Worker -->
  <script>
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/service-worker.js').then((reg) => {
      console.log('Service Worker registered:', reg);
    });
  }
  </script>

PWA Tutorial

Contents

5.4. PWA Tutorial#

5.4.1. Setup#

Backend#

Frontend#

5.4.2. Installable PWA#

Manifest#

Icon#

5.4.3. Working Offline#

Service Worker#

Serving the Service Worker#

Online Event#

Register Service Worker#