nextjs-pwa（Next.js PWA 前端）

Next.js PWA Skill

Quick Reference

Quick Start — Serwist (Recommended)

Serwist is the actively maintained successor to next-pwa, built for App Router.

1. Install

npm install @serwist/next && npm install -D serwist

2. Create app/manifest.ts

import type { MetadataRoute } from "next";

export default function manifest(): MetadataRoute.Manifest {
  return {
    name: "My App",
    short_name: "App",
    description: "My Progressive Web App",
    start_url: "/",
    display: "standalone",
    background_color: "#ffffff",
    theme_color: "#000000",
    icons: [
      { src: "/icon-192.png", sizes: "192x192", type: "image/png" },
      { src: "/icon-512.png", sizes: "512x512", type: "image/png" },
    ],
  };
}

3. Create app/sw.ts (service worker)

import { defaultCache } from "@serwist/next/worker";
import type { PrecacheEntry, SerwistGlobalConfig } from "serwist";
import { Serwist } from "serwist";

declare global {
  interface WorkerGlobalScope extends SerwistGlobalConfig {
    __SW_MANIFEST: (PrecacheEntry | string)[] | undefined;
  }
}

declare const self: ServiceWorkerGlobalScope;

const serwist = new Serwist({
  precacheEntries: self.__SW_MANIFEST,
  skipWaiting: true,
  clientsClaim: true,
  navigationPreload: true,
  runtimeCaching: defaultCache,
});

serwist.addEventListeners();

4. Update next.config.ts

import withSerwist from "@serwist/next";

const nextConfig = {
  // your existing config
};

export default withSerwist({
  swSrc: "app/sw.ts",
  swDest: "public/sw.js",
  disable: process.env.NODE_ENV === "development",
})(nextConfig);

That's it — 4 files for a working PWA. Run next build and test with Lighthouse.

Quick Start — Manual (No Dependencies)

Use this when you want zero dependencies or are using output: "export".

1. Create app/manifest.ts

Same as above.

2. Create public/sw.js

const CACHE_NAME = "app-v1";
const PRECACHE_URLS = ["/", "/offline"];

self.addEventListener("install", (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
  );
  self.skipWaiting();
});

self.addEventListener("activate", (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
  self.clients.claim();
});

self.addEventListener("fetch", (event) => {
  if (event.request.mode === "navigate") {
    event.respondWith(
      fetch(event.request).catch(() => caches.match("/offline"))
    );
    return;
  }
  event.respondWith(
    caches.match(event.request).then((cached) => cached || fetch(event.request))
  );
});

3. Register SW in layout

// app/components/ServiceWorkerRegistration.tsx
"use client";

import { useEffect } from "react";

export function ServiceWorkerRegistration() {
  useEffect(() => {
    if ("serviceWorker" in navigator) {
      navigator.serviceWorker.register("/sw.js");
    }
  }, []);
  return null;
}

Add <ServiceWorkerRegistration /> to your root layout.

Decision Framework

Web App Manifest

Next.js 13.3+ supports app/manifest.ts natively. This generates /manifest.webmanifest at build time.

Key fields

{
  name: "Full App Name",              // install dialog, splash screen
  short_name: "App",                  // home screen label (≤12 chars)
  description: "What the app does",
  start_url: "/",                     // entry point on launch
  display: "standalone",              // standalone | fullscreen | minimal-ui | browser
  orientation: "portrait",            // optional: lock orientation
  background_color: "#ffffff",        // splash screen background
  theme_color: "#000000",             // browser chrome color
  icons: [
    { src: "/icon-192.png", sizes: "192x192", type: "image/png" },
    { src: "/icon-512.png", sizes: "512x512", type: "image/png" },
    { src: "/icon-maskable.png", sizes: "512x512", type: "image/png", purpose: "maskable" },
  ],
  screenshots: [                      // optional: richer install UI
    { src: "/screenshot-wide.png", sizes: "1280x720", type: "image/png", form_factor: "wide" },
    { src: "/screenshot-narrow.png", sizes: "640x1136", type: "image/png", form_factor: "narrow" },
  ],
}

Manifest tips

• Always include both 192x192 and 512x512 icons (Lighthouse requirement)
• Add a maskable icon for Android adaptive icons
• screenshots enable the richer install sheet on Android/desktop Chrome
• theme_color should match your <meta name="theme-color"> in layout

Service Worker Essentials

Lifecycle

1. Install — SW downloaded, install event fires, precache assets
2. Waiting — New SW waits for all tabs to close (unless skipWaiting)
3. Activate — Old caches cleaned up, SW takes control
4. Fetch — SW intercepts network requests

Update flow

When a new SW is detected:

• skipWaiting: true — immediately activates (may break in-flight requests)
• Without skipWaiting — waits for all tabs to close, then activates
• Notify users of updates with workbox-window or manual controllerchange listener

Registration scope

• SW at /sw.js controls all pages under /
• SW at /app/sw.js only controls /app/*
• Always place SW at root unless you have a specific reason not to

Caching Strategies Quick Reference

Serwist's defaultCache provides sensible defaults. For custom strategies, see references/caching-strategies.md.

Offline Support Basics

App shell pattern

Precache the app shell (layout, styles, scripts) so the UI loads instantly offline. Dynamic content loads from cache or shows a fallback.

Online/offline detection hook

"use client";
import { useSyncExternalStore } from "react";

function subscribe(callback: () => void) {
  window.addEventListener("online", callback);
  window.addEventListener("offline", callback);
  return () => {
    window.removeEventListener("online", callback);
    window.removeEventListener("offline", callback);
  };
}

export function useOnlineStatus() {
  return useSyncExternalStore(
    subscribe,
    () => navigator.onLine,
    () => true // SSR: assume online
  );
}

Offline fallback page

Create app/offline/page.tsx and precache /offline in your SW. When navigation fails, serve this page.

For IndexedDB, background sync, and advanced offline patterns, see references/offline-data.md.

Install Prompt Handling

beforeinstallprompt (Chrome/Edge/Android)

"use client";
import { useState, useEffect } from "react";

export function InstallPrompt() {
  const [deferredPrompt, setDeferredPrompt] = useState<any>(null);

  useEffect(() => {
    const handler = (e: Event) => {
      e.preventDefault();
      setDeferredPrompt(e);
    };
    window.addEventListener("beforeinstallprompt", handler);
    return () => window.removeEventListener("beforeinstallprompt", handler);
  }, []);

  if (!deferredPrompt) return null;

  return (
    <button
      onClick={async () => {
        deferredPrompt.prompt();
        const { outcome } = await deferredPrompt.userChoice;
        if (outcome === "accepted") setDeferredPrompt(null);
      }}
    >
      Install App
    </button>
  );
}

iOS detection

iOS doesn't fire beforeinstallprompt. Detect iOS and show manual instructions:

function isIOS() {
  return /iPad|iPhone|iPod/.test(navigator.userAgent) && !(window as any).MSStream;
}

function isStandalone() {
  return window.matchMedia("(display-mode: standalone)").matches
    || (navigator as any).standalone === true;
}

Show a banner: "Tap Share then Add to Home Screen" for iOS Safari users.

Push Notifications Quick Start

1. Generate VAPID keys

npx web-push generate-vapid-keys

2. Subscribe in client

async function subscribeToPush() {
  const reg = await navigator.serviceWorker.ready;
  const sub = await reg.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY,
  });
  await fetch("/api/push/subscribe", {
    method: "POST",
    body: JSON.stringify(sub),
  });
}

3. Handle in SW

self.addEventListener("push", (event) => {
  const data = event.data?.json() ?? { title: "Notification" };
  event.waitUntil(
    self.registration.showNotification(data.title, {
      body: data.body,
      icon: "/icon-192.png",
    })
  );
});

For server-side sending, VAPID setup, and full implementation, see references/push-notifications.md.

Troubleshooting Cheat Sheet

For detailed debugging steps, see references/troubleshooting.md.

Assets & Templates

• assets/manifest-template.ts — Complete app/manifest.ts with all fields
• assets/sw-serwist-template.ts — Serwist SW with custom routes and offline fallback
• assets/sw-manual-template.js — Manual SW with all strategies
• assets/next-config-serwist.ts — next.config.ts with withSerwist

Generator Script

python scripts/generate_pwa_config.py <project-name> --approach serwist|manual [--push] [--offline]

Scaffolds PWA files based on chosen approach and features.