Pwa

Type definitions and utilities for Progressive Web App features.

PWA Library

Type definitions and utilities for Progressive Web App features.

Overview

This library provides TypeScript types and helper functions for managing PWA configuration, including:

• Web App Manifest structure and validation
• Theme color configuration for light/dark modes
• Service worker registration and lifecycle management
• Icon generation configuration

Modules

manifest.ts

Web App Manifest types per W3C specification.

Key Types:

• PWAManifest - Manifest configuration
• PWAIcon - Icon definition with size, type, and purpose
• IconGenerationConfig - Configuration for icon generation script
• DisplayMode - PWA display modes (standalone, fullscreen, etc.)

Utilities:

• validateManifestIcons() - Validates icon configuration
• REQUIRED_ICON_SIZES - Standard icon sizes for PWA (16, 32, 180, 192, 512)
• MASKABLE_ICON_SIZES - Sizes that need maskable variants (192, 512)

Example:

import { PWAManifest, validateManifestIcons } from "@/lib/pwa";

const manifest: PWAManifest = {
  name: "My App",
  short_name: "App",
  display: "standalone",
  icons: [
    {
      src: "/icon-192x192.png",
      sizes: "192x192",
      type: "image/png",
      purpose: "any",
    },
  ],
  // ...
};

const validation = validateManifestIcons(manifest.icons);
if (!validation.valid) {
  console.error("Missing icon sizes:", validation.missing);
}

theme-color.ts

Theme color configuration for dynamic light/dark mode support.

Key Types:

• ThemeColorConfig - Light and dark theme colors
• ThemeColorDefinition - Single theme color with media query
• AppleWebAppConfig - iOS-specific PWA settings

Utilities:

• createThemeColorConfig() - Creates config from hex colors
• toMetadataFormat() - Converts to Next.js metadata format
• validateThemeColors() - Validates hex color format

Example:

import { createThemeColorConfig, toMetadataFormat } from "@/lib/pwa";

const themeColors = createThemeColorConfig("#ffffff", "#0a0f1f");
// {
//   light: { media: "(prefers-color-scheme: light)", color: "#ffffff" },
//   dark: { media: "(prefers-color-scheme: dark)", color: "#0a0f1f" }
// }

const metadataColors = toMetadataFormat(themeColors);
// Use in Next.js metadata API

service-worker.ts

Service worker registration and caching strategy configuration.

Key Types:

• ServiceWorkerConfig - Service worker configuration
• CachingStrategy - Strategies: cache-first, network-first, network-required, etc.
• CacheRule - URL pattern matching for cache strategies
• ServiceWorkerRegistration - Registration result with update status

Utilities:

• registerServiceWorker() - Registers service worker with config
• checkForUpdates() - Manually checks for SW updates
• unregisterServiceWorker() - Removes service worker
• getCurrentServiceWorker() - Gets active SW controller
• validateServiceWorkerConfig() - Validates configuration

Example:

import {
  registerServiceWorker,
  DEFAULT_SERVICE_WORKER_CONFIG,
} from "@/lib/pwa";

// Use default configuration
const registration = await registerServiceWorker();

// Or customize
const customConfig = {
  ...DEFAULT_SERVICE_WORKER_CONFIG,
  cacheRules: [
    { pattern: /^\/api\//, strategy: "network-required" },
    { pattern: /\.js$/, strategy: "cache-first" },
  ],
};

const result = await registerServiceWorker(customConfig);
if (result?.isUpdate) {
  console.log("Service worker updated");
}

Caching Strategies

The library supports multiple caching strategies per FR-031:

network-required

Always use network. Return error response if network unavailable.

• Use for: API calls requiring fresh data (geocoding)

cache-first

Check cache first, update in background.

• Use for: Static assets (JS, CSS, images)

network-first

Try network first, fall back to cache.

• Use for: HTML pages

cache-only

Only serve from cache, never network.

• Use for: Critical offline resources

network-only

Always use network, never cache.

• Use for: Real-time data

Integration

With Next.js Metadata API

import { createThemeColorConfig, toMetadataFormat } from "@/lib/pwa";
import type { Metadata } from "next";

const themeColors = createThemeColorConfig("#ffffff", "#0a0f1f");

export const metadata: Metadata = {
  manifest: "/manifest.json",
  themeColor: toMetadataFormat(themeColors),
  appleWebApp: {
    capable: true,
    statusBarStyle: "default",
    title: "My App",
  },
};

With Service Worker Registration

"use client";

import { useEffect } from "react";
import { registerServiceWorker } from "@/lib/pwa";

export function ServiceWorkerRegistration() {
  useEffect(() => {
    if (process.env.NODE_ENV === "production") {
      registerServiceWorker().then((result) => {
        if (result?.isUpdate) {
          console.log("New service worker available");
        }
      });
    }
  }, []);

  return null;
}

With Icon Generation Script

import { IconGenerationConfig, REQUIRED_ICON_SIZES } from "@/lib/pwa";

const icons: IconGenerationConfig[] = REQUIRED_ICON_SIZES.map((size) => ({
  name: `icon-${size}x${size}.png`,
  size,
  purpose: `PWA icon (${size}x${size})`,
  maskable: size >= 192, // Maskable for larger icons
}));

Related Files

• public/manifest.json - Actual PWA manifest file
• public/sw.js - Service worker implementation
• src/components/pwa/service-worker-registration.tsx - React component for SW registration
• scripts/generate-icons.ts - Icon generation script
• docs/pwa-setup.md - PWA implementation guide

References

• W3C Web App Manifest
• MDN: Service Worker API
• MDN: Progressive Web Apps
• Web.dev: PWA Checklist
• Maskable Icons