Add Pwa

Add PWA Support

Adds Progressive Web App capabilities to a Next.js project using @serwist/turbopack — the Turbopack-compatible Serwist integration. Uses esbuild via a Route Handler to bundle the service worker, so no webpack fallback is needed. Provides installability, offline support, precaching, and runtime caching strategies out of the box.

What Gets Created

Prerequisites

• Next.js 15+ project (App Router)
• TypeScript configured

Installation

bun add -D @serwist/turbopack esbuild serwist

Setup Steps

1. Create Web App Manifest

Create app/manifest.ts:

import type { MetadataRoute } from "next";

export default function manifest(): MetadataRoute.Manifest {
  return {
    name: "My App",
    short_name: "MyApp",
    description: "A Progressive Web App built with Next.js",
    start_url: "/",
    display: "standalone",
    background_color: "#ffffff",
    theme_color: "#000000",
    orientation: "portrait",
    icons: [
      {
        src: "/icons/icon-192x192.svg",
        sizes: "192x192",
        type: "image/svg+xml",
        purpose: "maskable",
      },
      {
        src: "/icons/icon-512x512.svg",
        sizes: "512x512",
        type: "image/svg+xml",
      },
    ],
  };
}

Note: Next.js automatically serves this at /manifest.webmanifest and adds the <link rel="manifest"> tag. No manual <link> tag needed. Replace SVG placeholders with real PNG icons for production.

2. Create Service Worker

Create app/sw.ts:

/// <reference no-default-lib="true" />
/// <reference lib="esnext" />
/// <reference lib="webworker" />
import { defaultCache } from "@serwist/turbopack/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,
  fallbacks: {
    entries: [
      {
        url: "/~offline",
        matcher({ request }) {
          return request.destination === "document";
        },
      },
    ],
  },
});

serwist.addEventListeners();

Important: The /// <reference no-default-lib="true" /> directive removes default type definitions (including dom) from the compilation scope. You must exclude this file from the main TypeScript compilation. Add "app/sw.ts" to the exclude array in tsconfig.json:

{
  "exclude": ["node_modules", "app/sw.ts"]
}

This is safe because app/sw.ts is bundled separately by esbuild via the route handler — it does not go through the normal tsc / Next.js compilation pipeline.

3. Create Serwist Route Handler

Create app/serwist/[path]/route.ts:

import { spawnSync } from "node:child_process";
import { createSerwistRoute } from "@serwist/turbopack";

const revision =
  spawnSync("git", ["rev-parse", "HEAD"], { encoding: "utf-8" }).stdout.trim() ||
  crypto.randomUUID();

export const { dynamic, dynamicParams, revalidate, generateStaticParams, GET } =
  createSerwistRoute({
    additionalPrecacheEntries: [{ url: "/~offline", revision }],
    swSrc: "app/sw.ts", // Use "src/app/sw.ts" if project has --src-dir
    useNativeEsbuild: true,
  });

This route handler uses esbuild to bundle app/sw.ts on-demand, injecting the precache manifest. The compiled service worker is served at /serwist/sw.js.

4. Create Offline Fallback Page

Create app/~offline/page.tsx:

export default function OfflinePage() {
  return (
    <div className="flex min-h-screen items-center justify-center bg-background">
      <div className="text-center px-6">
        <div className="text-6xl mb-6">📡</div>
        <h1 className="text-2xl font-bold text-foreground mb-2">
          You&apos;re offline
        </h1>
        <p className="text-muted-foreground max-w-sm">
          Check your internet connection and try again. Some features may still
          be available offline.
        </p>
      </div>
    </div>
  );
}

5. Configure next.config.ts

Update next.config.ts to wrap with Serwist:

import { withSerwist } from "@serwist/turbopack";

export default withSerwist({
  // Your existing Next.js config goes here
});

Important: If the project has an existing next.config.ts with other config (e.g. reactCompiler: true), pass it inside the withSerwist() call:

import { withSerwist } from "@serwist/turbopack";

export default withSerwist({
  reactCompiler: true,
  // ...other config
});

6. Create SerwistProvider Re-export

Create app/serwist-provider.tsx:

"use client";
export { SerwistProvider } from "@serwist/turbopack/react";

Serwist's SerwistProvider must be used in a client component. This re-export adds the "use client" directive.

7. Update Root Layout Metadata & Wire Up Provider

Update app/layout.tsx to include PWA metadata and the Serwist provider:

import type { Metadata, Viewport } from "next";
import { SerwistProvider } from "./serwist-provider";
import { PWAInstallPrompt } from "@/components/pwa-install-prompt";
import { PWAProvider } from "@/components/pwa-provider";

export const metadata: Metadata = {
  applicationName: "My App",
  title: {
    default: "My App",
    template: "%s | My App",
  },
  description: "A Progressive Web App built with Next.js",
  appleWebApp: {
    capable: true,
    statusBarStyle: "default",
    title: "My App",
  },
  formatDetection: {
    telephone: false,
  },
};

export const viewport: Viewport = {
  themeColor: "#000000",
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SerwistProvider swUrl="/serwist/sw.js">
          <PWAProvider>
            {children}
            <PWAInstallPrompt />
          </PWAProvider>
        </SerwistProvider>
      </body>
    </html>
  );
}

Note: themeColor must be in the viewport export, not metadata (changed in Next.js 14+). The swUrl points to the route handler path, not a static file.

8. Generate Placeholder Icons

Create scripts/generate-icons.ts:

import { mkdirSync, writeFileSync } from "node:fs";

function generatePlaceholderSVG(size: number): string {
  return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">
  <rect width="${size}" height="${size}" fill="#000000" rx="${size * 0.1}"/>
  <text x="50%" y="50%" dominant-baseline="central" text-anchor="middle" fill="white" font-family="system-ui" font-size="${size * 0.4}" font-weight="bold">App</text>
</svg>`;
}

mkdirSync("public/icons", { recursive: true });

for (const size of [192, 512]) {
  writeFileSync(
    `public/icons/icon-${size}x${size}.svg`,
    generatePlaceholderSVG(size),
  );
}

writeFileSync("public/icons/apple-touch-icon.svg", generatePlaceholderSVG(180));

Run it:

bun run scripts/generate-icons.ts

For production, replace these SVGs with real PNG icons using Real Favicon Generator and update app/manifest.ts to use type: "image/png".

9. Create PWA Provider Component

Create components/pwa-provider.tsx:

"use client";

import {
  createContext,
  useContext,
  useMemo,
  useSyncExternalStore,
} from "react";

type PWAContextValue = {
  isOnline: boolean;
  isInstalled: boolean;
};

const PWAContext = createContext<PWAContextValue>({
  isOnline: true,
  isInstalled: false,
});

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

function getOnlineSnapshot() {
  return navigator.onLine;
}

function getServerSnapshot() {
  return true;
}

function subscribeDisplayMode(callback: () => void) {
  const mql = window.matchMedia("(display-mode: standalone)");
  mql.addEventListener("change", callback);
  return () => mql.removeEventListener("change", callback);
}

function getDisplayModeSnapshot() {
  return window.matchMedia("(display-mode: standalone)").matches;
}

function getDisplayModeServerSnapshot() {
  return false;
}

export function PWAProvider({ children }: { children: React.ReactNode }) {
  const isOnline = useSyncExternalStore(
    subscribeOnline,
    getOnlineSnapshot,
    getServerSnapshot,
  );
  const isInstalled = useSyncExternalStore(
    subscribeDisplayMode,
    getDisplayModeSnapshot,
    getDisplayModeServerSnapshot,
  );

  const value = useMemo(
    () => ({ isOnline, isInstalled }),
    [isOnline, isInstalled],
  );

  return <PWAContext value={value}>{children}</PWAContext>;
}

export function usePWA() {
  return useContext(PWAContext);
}

10. Create Install Prompt Component

Create components/pwa-install-prompt.tsx:

"use client";

import { useCallback, useEffect, useRef, useState } from "react";

type BeforeInstallPromptEvent = Event & {
  prompt(): Promise<void>;
  userChoice: Promise<{ outcome: "accepted" | "dismissed" }>;
};

export function PWAInstallPrompt() {
  const deferredPromptRef = useRef<BeforeInstallPromptEvent | null>(null);
  const [showPrompt, setShowPrompt] = useState(false);

  useEffect(() => {
    function handleBeforeInstallPrompt(e: Event) {
      e.preventDefault();
      deferredPromptRef.current = e as BeforeInstallPromptEvent;
      setShowPrompt(true);
    }

    window.addEventListener("beforeinstallprompt", handleBeforeInstallPrompt);
    return () =>
      window.removeEventListener(
        "beforeinstallprompt",
        handleBeforeInstallPrompt,
      );
  }, []);

  const handleInstall = useCallback(async () => {
    const prompt = deferredPromptRef.current;
    if (!prompt) return;

    await prompt.prompt();
    const { outcome } = await prompt.userChoice;

    if (outcome === "accepted") {
      deferredPromptRef.current = null;
      setShowPrompt(false);
    }
  }, []);

  const handleDismiss = useCallback(() => {
    setShowPrompt(false);
    deferredPromptRef.current = null;
  }, []);

  if (!showPrompt) return null;

  return (
    <div className="fixed bottom-4 left-4 right-4 z-50 mx-auto max-w-md rounded-lg border border-border bg-card p-4 shadow-lg">
      <div className="flex items-start gap-3">
        <div className="flex-1">
          <p className="font-medium text-foreground">Install App</p>
          <p className="text-sm text-muted-foreground">
            Add this app to your home screen for a better experience.
          </p>
        </div>
        <div className="flex gap-2">
          <button
            type="button"
           
            className="rounded-md px-3 py-1.5 text-sm text-muted-foreground hover:bg-muted"
          >
            Later
          </button>
          <button
            type="button"
           
            className="rounded-md bg-primary px-3 py-1.5 text-sm text-primary-foreground hover:bg-primary/90"
          >
            Install
          </button>
        </div>
      </div>
    </div>
  );
}

Usage Examples

Check Online/Offline Status

"use client";

import { usePWA } from "@/components/pwa-provider";

export function ConnectionStatus() {
  const { isOnline } = usePWA();

  return (
    <div className="flex items-center gap-2">
      <div className={`h-2 w-2 rounded-full ${isOnline ? "bg-green-500" : "bg-red-500"}`} />
      <span className="text-sm text-muted-foreground">
        {isOnline ? "Online" : "Offline"}
      </span>
    </div>
  );
}

Check if Running as Installed PWA

"use client";

import { usePWA } from "@/components/pwa-provider";

export function AppHeader() {
  const { isInstalled } = usePWA();

  return (
    <header className="border-b border-border bg-card px-4 py-3">
      <h1 className="text-foreground font-bold">
        My App {isInstalled && <span className="text-xs text-muted-foreground">(Installed)</span>}
      </h1>
    </header>
  );
}

Testing Checklist

• bun run build completes without errors (uses Turbopack — no --webpack flag needed)
• bun dev starts without errors (Turbopack, no fallback)
• /serwist/sw.js is served correctly (check in browser)
• /manifest.webmanifest is served correctly
• App is installable (Chrome shows install icon in address bar)
• Install prompt banner appears on first visit
• Offline fallback page shows when navigating offline
• Online/offline status updates in real time
• No TypeScript errors
• Service worker registers on page load (check DevTools > Application > Service Workers)

Troubleshooting

Service worker not updating in development

With @serwist/turbopack, the service worker is bundled by esbuild via the route handler. In dev mode, changes to app/sw.ts require a dev server restart to take effect. This is a known limitation — esbuild bundles once per server start.

TypeScript errors (Cannot find name 'window', etc.)

The /// <reference no-default-lib="true" /> directive in app/sw.ts removes all default type definitions (including dom) from the compilation scope. If app/sw.ts is not excluded from tsconfig.json, this breaks type-checking for the entire project.

Fix: Ensure "app/sw.ts" is in the exclude array of tsconfig.json:

{
  "exclude": ["node_modules", "app/sw.ts"]
}

If your IDE still shows errors in sw.ts itself, that is expected — esbuild bundles the file separately and does not use tsconfig.json.

Route handler 404 at /serwist/sw.js

Ensure the file is at exactly app/serwist/[path]/route.ts (with the [path] dynamic segment). The generateStaticParams export pre-renders sw.js and sw.js.map.

Icons not showing on install

• Verify icons exist at the exact paths specified in app/manifest.ts
• Ensure at least a 192x192 and 512x512 icon are provided
• Use purpose: "maskable" on the 192x192 icon for adaptive icon support
• Test with Chrome DevTools > Application > Manifest

Offline page not showing

• Ensure /~offline route exists and renders without errors
• The offline fallback only works for navigation requests (HTML pages), not API calls or assets
• Verify additionalPrecacheEntries in the route handler includes { url: "/~offline", revision }

Migrating from @serwist/next (webpack)

If upgrading from the webpack-based setup:

1. Remove @serwist/next: bun remove @serwist/next
2. Install turbopack version: bun add -D @serwist/turbopack esbuild
3. Replace next.config.ts — use { withSerwist } from "@serwist/turbopack" instead of withSerwistInit from "@serwist/next"
4. Create the route handler at app/serwist/[path]/route.ts
5. Create the app/serwist-provider.tsx re-export
6. Update app/sw.ts imports: @serwist/turbopack/worker instead of @serwist/next/worker
7. Remove turbopack: {} workaround from next.config.ts (no longer needed)
8. Remove --webpack flags from package.json scripts
9. Remove public/sw.js and public/sw.js.map from .gitignore (no longer generated as static files)
10. Remove @serwist/next/typings from tsconfig.json types (triple-slash directives handle this now)
11. Remove "webworker" from tsconfig.json lib array (triple-slash directives in sw.ts handle this now)
12. Replace public/sw.js with app/sw.ts in tsconfig.json exclude array (the service worker is no longer generated as a static file, but still needs excluding due to /// <reference no-default-lib="true" />)