mirror of
https://github.com/Fenrir784/e621tagger.git
synced 2026-11-20 08:41:20 -08:00
17 KiB
17 KiB
PWA Documentation
This document provides comprehensive documentation of the Progressive Web App (PWA) implementation for e621tagger. It covers the service worker, manifest, and offline functionality.
PWA Components
| Component | File | Purpose |
|---|---|---|
| Service Worker | templates/service-worker.js |
Offline caching, network request interception |
| SW Registration | static/js/sw-init.js |
Service worker registration |
| Web Manifest | static/manifest.json |
App metadata, icons, display |
| Install Script | (in index.html) | Install prompt handling |
Service Worker
File Location
templates/service-worker.js
Version-Based Caching
const CACHE_VERSION = '{{APP_VERSION}}';
const CACHE_NAME = `e621tagger-${CACHE_VERSION}`;
const STATIC_CACHE = `${CACHE_NAME}-static`;
The cache includes the application version for easy invalidation.
Cached Resources
const urlsToCache = [
'/',
'/static/css/style.css',
'/static/js/script.js',
'/static/js/hammer.min.js',
'/static/js/sw-init.js',
'/static/manifest.json',
'/static/icons/favicon.svg',
'/static/icons/favicon.ico',
'/static/icons/apple-touch-icon.png',
'/static/icons/favicon-96x96.png',
'/static/icons/favicon-32x32.png',
'/static/icons/favicon-16x16.png',
'/static/icons/maskable_icon.png',
'/static/icons/maskable_icon_x512.png',
'/static/icons/maskable_icon_x384.png',
'/static/icons/maskable_icon_x192.png',
'/static/icons/maskable_icon_x128.png',
'/static/icons/maskable_icon_x96.png',
'/static/icons/maskable_icon_x72.png',
'/static/icons/maskable_icon_x48.png',
'/static/icons/egg/egg_top.png',
'/static/icons/egg/egg_bottom.png',
'/static/icons/egg/f1.png',
'/static/icons/egg/f2.png',
'/static/icons/egg/f3.png',
'/static/icons/egg/f4.png',
'/static/icons/egg/f5.png',
'/static/icons/egg/f6.png',
'/static/icons/egg/f7.png',
'/static/icons/egg/f8.png',
'/static/icons/egg/f9.png'
];
Total: 31 cached resources
Service Worker Life Cycle
Install Event
self.addEventListener('install', event => {
event.waitUntil(
caches.open(STATIC_CACHE).then(cache => cache.addAll(urlsToCache))
);
self.skipWaiting();
});
Behavior:
- Open cache named with version
- Add all URLs to cache
- Call
skipWaiting()to activate immediately
Activate Event
self.addEventListener('activate', event => {
event.waitUntil(
caches.keys().then(keys => {
return Promise.all(
keys.map(key => {
if (key !== STATIC_CACHE) {
return caches.delete(key);
}
})
);
}).then(() => {
return clients.claim();
}).then(() => {
clients.matchAll({ type: 'window' }).then(clients => {
clients.forEach(client => {
client.postMessage({ action: 'reload' });
});
});
})
);
});
Behavior:
- Delete all old caches
- Claim existing clients
- Send
reloadmessage to all open windows
Fetch Event
self.addEventListener('fetch', event => {
const url = new URL(event.request.url);
const isStatic = url.pathname.startsWith('/static/') ||
url.pathname === '/favicon.ico' ||
url.pathname === '/manifest.json';
if (event.request.method !== 'GET') {
event.respondWith(fetch(event.request));
return;
}
if (url.pathname === '/predict' || url.pathname === '/health') {
event.respondWith(fetch(event.request));
return;
}
if (event.request.mode === 'navigate') {
event.respondWith(
fetch(event.request).catch(async () => {
const cache = await caches.open(STATIC_CACHE);
const cachedResponse = await cache.match('/');
if (cachedResponse) {
const clientsList = await clients.matchAll({ type: 'window' });
clientsList.forEach(client => {
client.postMessage({ action: 'offline' });
});
return cachedResponse;
}
return new Response('Offline: unable to load page', { status: 503 });
})
);
return;
}
if (isStatic) {
event.respondWith(
caches.match(event.request).then(cached => {
const fetchPromise = fetch(event.request).then(networkResponse => {
if (networkResponse && networkResponse.status === 200) {
const responseToCache = networkResponse.clone();
caches.open(STATIC_CACHE).then(cache => {
cache.put(event.request, responseToCache);
});
}
return networkResponse;
}).catch(() => null);
return cached || fetchPromise;
})
);
return;
}
event.respondWith(
caches.match(event.request).then(cached => {
if (cached) return cached;
return fetch(event.request).then(networkResponse => {
if (networkResponse && networkResponse.status === 200) {
const responseToCache = networkResponse.clone();
caches.open(STATIC_CACHE).then(cache => {
cache.put(event.request, responseToCache);
});
}
return networkResponse;
});
})
);
});
Request Strategies
| Request Type | Strategy | Behavior |
|---|---|---|
| Non-GET | Network | Always fetch |
/predict, /health |
Network | Always fetch |
| Navigation | Network-first with offline fallback | Try network, fallback to cache |
| Static assets | Cache-first | Try cache, fetch and cache |
| Other | Cache-first | Try cache, fetch and cache |
SW Registration
File Location
static/js/sw-init.js
Registration Code
if ('serviceWorker' in navigator) {
window.addEventListener('load', () => {
navigator.serviceWorker.register('/service-worker.js').then(reg => {
console.log('Service Worker registered:', reg);
}).catch(err => {
console.error('Service Worker registration failed:', err);
});
});
navigator.serviceWorker.addEventListener('message', event => {
if (event.data && event.data.action === 'reload') {
window.location.reload();
}
});
}
Behavior:
- Register service worker on page load
- Log registration status
- Listen for
reloadmessage from SW
Web Manifest
File Location
static/manifest.json
Manifest Content
{
"name": "e621tagger",
"short_name": "e621tagger",
"description": "Free web-based e621 tagging app created for furries by furries.",
"id": "/",
"start_url": "/",
"scope": "/",
"display": "standalone",
"display_override": ["window-controls-overlay", "standalone"],
"orientation": "portrait",
"theme_color": "#8b4aff",
"background_color": "#0a0c10",
"categories": ["utilities", "productivity", "multimedia"],
"icons": [...],
"screenshots": [...],
"related_applications": [],
"prefer_related_applications": false
}
Manifest Fields
| Field | Value | Description |
|---|---|---|
name |
e621tagger | Full app name |
short_name |
e621tagger | Short name for home screen |
description |
... | App description |
id |
/ | Unique app identifier |
start_url |
/ | Launch URL |
scope |
/ | Navigation scope |
display |
standalone | Display as standalone app |
orientation |
portrait | Lock to portrait |
theme_color |
#8b4aff | App theme color |
background_color |
#0a0c10 | Splash screen background |
Icons
| Size | File | Purpose |
|---|---|---|
| 48x48 | maskable_icon_x48.png | Small icon |
| 72x72 | maskable_icon_x72.png | |
| 96x96 | maskable_icon_x96.png | Favicon |
| 128x128 | maskable_icon_x128.png | |
| 192x192 | maskable_icon_x192.png | App icon |
| 384x384 | maskable_icon_x384.png | |
| 512x512 | maskable_icon_x512.png | Large icon |
| 1024x1024 | maskable_icon.png | Store listing |
Icon Purposes
{
"purpose": "any",
"sizes": "1024x1024",
"src": "/static/icons/maskable_icon.png",
"type": "image/png"
}
| Purpose | Description |
|---|---|
any |
Used at any size |
maskable |
Designed for masking (adaptive icons) |
Screenshots
"screenshots": [
{
"src": "/static/screenshots/desktop1.webp",
"sizes": "1920x1080",
"type": "image/webp",
"form_factor": "wide",
"label": "Desktop view 1"
},
{
"src": "/static/screenshots/desktop2.webp",
"sizes": "1920x1080",
"type": "image/webp",
"form_factor": "wide",
"label": "Desktop view 2"
},
{
"src": "/static/screenshots/mobile1.webp",
"sizes": "1080x1920",
"type": "image/webp",
"label": "Mobile view 1"
},
{
"src": "/static/screenshots/mobile2.webp",
"sizes": "1080x1920",
"type": "image/webp",
"label": "Mobile view 2"
}
]
Display Modes
Standalone
"display": "standalone"
| Mode | Description |
|---|---|
standalone |
Full screen, no browser chrome |
fullscreen |
Full screen |
minimal-ui |
Minimal browser UI |
browser |
Normal browser tab |
Installation
Browser Prompts
Browsers show "Install" button when PWA criteria are met.
HTML Integration
<link rel="manifest" href="/static/manifest.json">
Offline Functionality
What's Cached
| Type | Available Offline |
|---|---|
| App UI | Yes (returns cached /) |
| Static assets | Yes |
| /predict | No (network only) |
| /health | No (network only) |
Offline Handling
- Navigation: Return cached
/if available - Static: Return cached or fetch-and-cache
- API: Network only
Notification
When offline navigation is served:
client.postMessage({ action: 'offline' });
Frontend listens:
navigator.serviceWorker.addEventListener('message', event => {
if (event.data.action === 'offline') {
// Show offline notification
}
});
Update Flow
1. New version deployed
│
▼
2. Service worker updated
│
▼
3. skipWaiting() called
│
▼
4. New SW activates immediately
│
▼
5. Old caches deleted
│
▼
6. clients.claim() called
│
▼
7. 'reload' message sent to windows
│
▼
8. Page reloads
Cache Invalidation
The cache is version-based:
- Cache name:
e621tagger-{VERSION}-static - Version changes on each deployment
- Old cache deleted on activation
Browser Support
| Feature support | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|
| Service Worker | 40+ | 44+ | 15.2+ | 79+ |
| Web Manifest | 50+ | 75+ | 15.2+ | 79+ |
| Install Prompt | 60+ | - | 15.2+ | 79+ |
Debugging
Chrome DevTools
- Open DevTools (F12)
- Go to Application → Service Workers
- Check status, update, unregister
Check Cache
Application → Cache Storage → e621tagger-{version}-static
Network Logs
Network → check /service-worker.js
Testing
Test Offline
- Open app in Chrome
- DevTools → Network → Offline
- Reload page
- Should show cached UI
Test Update
- Deploy new version
- Visit app (old SW catches fetch)
- New SW activates in background
- Refresh page loads new version
Lighthouse Audit
# Run PWA audit
lighthouse https://tagger.fenrir784.app \
--only-categories=pwa \
--output=json \
--output-path=pwa-report.json
PWA Score Metrics
| Audit | Required |
|---|---|
| Registers SW | Yes |
| Has manifest | Yes |
| manifest.* properties | Yes |
| icons.* properties | Yes |
| Service Worker responds | Yes |
| start_url matches | Yes |
Complete Flow Diagram
┌─────────────────────────────────────────────────────────────┐
│ PWA Architecture │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Browser │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ sw-init.js │ │ │
│ │ │ - Register /service-worker.js │ │ │
│ │ │ - Listen for 'reload' message │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Service Worker │ │ │
│ │ │ │ │ │
│ │ │ ┌───────────────────────────────────────┐ │ │ │
│ │ │ │ Install: Cache 31 resources │ │ │ │
│ │ │ │ activate: Clean old caches │ │ │ │
│ │ │ │ fetch: Cache-first + network │ │ │ │
│ │ │ │ fetch: Network-first /predict │ │ │ │
│ │ │ └───────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Cache Storage │ │
│ │ e621tagger-{version}-static │ │
│ │ ├── / (cached) │ │
│ │ ├── /static/css/style.css │ │
│ │ ├── /static/js/script.js │ │
│ │ └── ... (31 resources) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
HTTP Caching Headers
Service Worker Script
# app.py
@app.route('/service-worker.js')
def service_worker():
response = make_response(render_template('service-worker.js', ...))
response.headers['Cache-Control'] = 'no-cache, no-store, must-revalidate'
response.headers['Pragma'] = 'no-cache'
response.headers['Expires'] = '0'
return response
| Header | Value |
|---|---|
| Cache-Control | no-cache, no-store, must-revalidate |
| Pragma | no-cache |
| Expires | 0 |
Purpose: Prevent browser from caching SW, ensure SW cache is used.
Static Assets
@app.route('/static/<path:filename>')
def static_files(filename):
response = make_response(send_from_directory('static', filename))
response.headers['Cache-Control'] = 'public, max-age=86400'
return response
| Header | Value |
|---|---|
| Cache-Control | public, max-age=86400 |
Purpose: Cache static assets for 24 hours (HTTP cache, not SW cache).
Chrome Display Override
"display_override": ["window-controls-overlay", "standalone"]
Enables Windows window controls on desktop.
Integration Checklist
/service-worker.jsendpoint in Flask- Cache version based on
APP_VERSION - 31 resources cached
- Network-first for navigation
- Cache-first for static assets
- Clean old caches on update
- Reload message on update
- Offline fallback for navigation
/static/manifest.jsonfor PWA- Icons in multiple sizes
- Screenshots for store listing
- Proper theme colors
- Standalone display mode