PWA (Progressive Web App)

Fuwafuwa Framework includes built-in Progressive Web App (PWA) support, allowing your application to work offline, be installed on devices, and provide a native app-like experience.

Progressive Web Apps represent the next evolution of web applications, bridging the gap between web and native mobile apps. By leveraging modern web technologies, PWAs deliver app-like experiences directly through the browser—no app store required. Users can install your app on their home screen, launch it with a single tap, and interact with it even when offline.

The PWA features in Fuwafuwa Framework are designed to be easy to implement while providing powerful capabilities. Service workers handle intelligent caching strategies, the web app manifest enables installation, and background sync ensures data isn't lost during connectivity issues. Together, these features create a resilient, engaging user experience that rivals native applications.

Web App Manifest

The web app manifest is a JSON file that tells the browser how your web application should appear and behave when installed on a device. It's the key that transforms your website into an installable app with its own icon, name, and display mode.

When users install your PWA, the browser reads the manifest to determine how to present the app. This includes the app name displayed on the home screen, the icons used at various sizes, the theme color that influences the browser UI, and whether the app launches in fullscreen or as a regular browser window.

The manifest.json file defines your app's metadata:

{
  "name": "My Fuwafuwa App",
  "short_name": "MyApp",
  "description": "A description of my application",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#3b82f6",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Manifest Properties

Service Worker

The service worker is the heart of PWA functionality—a JavaScript file that runs separately from your main application, intercepting network requests and managing caching. Service workers enable offline functionality, improve performance through strategic caching, and provide features like background sync.

Unlike regular JavaScript, service workers have special capabilities: they can intercept and modify network requests, cache resources for offline use, and run even when the user isn't actively using your app. This makes them perfect for implementing sophisticated caching strategies and ensuring your app works regardless of network conditions.

The service worker enables offline functionality and caching strategies:

// sw.js - Service Worker
const CACHE_NAME = 'fuwafuwa-v1';
const urlsToCache = [
  '/',
  '/css/styles.opt.min.css',
  '/js/app.min.js',
  '/icon-192.png'
];

// Install event - cache assets
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(urlsToCache))
  );
});

// Fetch event - serve from cache or network
self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request)
      .then(response => {
        // Return cached or fetch from network
        return response || fetch(event.request);
      })
  );
});

// Activate event - clean up old caches
self.addEventListener('activate', event => {
  event.waitUntil(
    caches.keys().then(cacheNames => {
      return Promise.all(
        cacheNames
          .filter(name => name !== CACHE_NAME)
          .map(name => caches.delete(name))
      );
    })
  );
});

How It Works

The service worker lifecycle consists of three main events: install, activate, and fetch. During installation, you cache essential assets. On activation, you clean up old caches. For every network request, the fetch event intercepts and decides whether to serve from cache, network, or both.

This example uses a simple "cache first" strategy—serve from cache if available, otherwise fetch from network. More sophisticated strategies include "network first" for real-time data, "stale while revalidate" for frequently updated content, and "cache only" for static assets that never change.

Registering the Service Worker

A service worker file alone doesn't do anything—it needs to be registered by your main application. Registration tells the browser to start the service worker and begin intercepting network requests. This typically happens during page load, after your core application has initialized.

The registration process is asynchronous and returns a promise that resolves with a registration object. This object provides useful information about the service worker, including its state and methods to update or unregister it. Always check for browser support before registering, as service workers require HTTPS and aren't available in all browsers.

Register the service worker in your main JavaScript:

// Register service worker
if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js')
      .then(registration => {
        console.log('SW registered:', registration);
      })
      .catch(error => {
        console.log('SW registration failed:', error);
      });
  });
}

Registration Best Practices

Register the service worker after your page has loaded to avoid competing for resources with your main application. The load event ensures all critical resources have loaded first. Always handle registration errors gracefully—service worker registration can fail due to browser limitations, network issues, or security restrictions.

App Icons

App icons are the face of your PWA—they appear on home screens, in app switchers, and in install prompts. Creating icons in multiple sizes ensures your app looks crisp on all devices, from low-end Android phones to high-resolution desktop displays.

Different platforms have different icon requirements. Android needs adaptive icons with foreground and background layers, iOS prefers rounded square icons, and desktop browsers may display any size. Generating icons at all standard sizes guarantees consistent presentation across all platforms.

Generate icons for different platforms:

Icon Generation Tools

Rather than creating icons manually at each size, use tools like:

• pwa-asset-generator - CLI tool for generating all required icons
• squoosh.app - Web-based image optimizer
• favicon.io - Online favicon and icon generator
• Maskable.app - Creates maskable icons for Android adaptive icons

Testing PWA Features

Proper testing is essential for a reliable PWA. Browser DevTools provide powerful inspection capabilities for service workers, and automated audits like Lighthouse can identify issues before users encounter them.

Browser DevTools

All major browsers include PWA debugging tools in their developer consoles:

• Chrome: DevTools → Application → Service Workers / Manifest
• Firefox: DevTools → Application → Service Workers
• Safari: Develop → Service Workers

Lighthouse Audit

Chrome's Lighthouse is an automated tool that audits your PWA against best practices and provides actionable feedback. It checks for manifest validity, service worker registration, HTTPS serving, mobile-friendliness, and more.

Run Chrome's Lighthouse audit to check PWA compliance:

1. Open DevTools (F12)
2. Go to Lighthouse tab
3. Select "PWA" category
4. Click "Generate report"

A good PWA score indicates your app meets the criteria for installation and offline functionality. Lighthouse also provides performance, accessibility, and SEO audits, making it a comprehensive tool for overall web app quality.

Deployment

PWAs require HTTPS to work (except on localhost). When deploying to production, ensure your server has a valid SSL certificate. Let's Encrypt provides free certificates that work well for this purpose. Once HTTPS is configured, your PWA features will be fully functional.

The Fuwafuwa Framework includes PWA files in the project root:

• manifest.json - Web app manifest configuration
• service-worker.js - Service worker with caching and offline support
• /images/icons/ - App icons in various sizes

These files are automatically linked in your application templates. No additional configuration is required—the PWA features work out of the box when served over HTTPS.