Usage

This page documents the main APIs and options in next-pwa-auto.

For fastest onboarding, run npx next-pwa-auto init first, then use this page for advanced options and overrides.

Plugin setup

import withPWAAuto from "next-pwa-auto";

export default withPWAAuto({
  disable: false,
  offline: true,
  icon: "./public/icon.png",
  manifest: {
    name: "My App",
    short_name: "MyApp",
    theme_color: "#000000",
    background_color: "#ffffff",
    display: "standalone",
  },
  cacheStrategies: {
    navigation: "networkFirst",
    staticAssets: "cacheFirst",
    images: "staleWhileRevalidate",
    api: "networkOnly",
  },
  workbox: {
    skipWaiting: true,
    clientsClaim: true,
  },
  pwaDir: "_pwa",
  disableInDev: true,
  swDest: "sw.js",
  scope: "/",
})({});

Config options

Option	Type	Default	Description
disable	boolean	false	Disables the plugin completely.
offline	boolean	true	Enables generated offline fallback page.
icon	string	Auto-detected	Source icon path.
manifest	Partial<WebAppManifest>	Auto-generated	Manifest overrides merged on top of defaults.
cacheStrategies	object	Safe defaults	Route-level cache strategy overrides.
workbox	object	Internal defaults	Additional Workbox GenerateSW options.
pwaDir	string	"_pwa"	Output directory under public/.
disableInDev	boolean	true	Disables service worker during next dev.
swDest	string	"sw.js"	Service worker destination filename.
scope	string	"/"	Service worker scope.

Advanced Workbox options

workbox is passed into GenerateSW with safe defaults.

workbox: {
  skipWaiting: true,
  clientsClaim: true,
  maximumFileSizeToCacheInBytes: 5 * 1024 * 1024,
  additionalManifestEntries: [{ url: "/robots.txt", revision: null }],
  exclude: [/\\.map$/, /^manifest.*\\.js$/],
}

Option	Type	Description
skipWaiting	boolean	Activates new SW immediately after install.
clientsClaim	boolean	Lets the active SW take control of open clients.
maximumFileSizeToCacheInBytes	number	Max asset size Workbox will precache.
additionalManifestEntries	Array<{ url: string; revision: string | null }>	Extra files to precache.
exclude	Array<string | RegExp>	Excludes matching files/paths from precache.

Caching defaults

next-pwa-auto uses production-safe defaults:

Route pattern	Default strategy	Purpose
Navigation requests	networkFirst	Fresh pages first, fallback when offline.
/_next/static/*	cacheFirst	Immutable build assets cached long-term.
/_next/data/*	networkFirst	Keeps server-rendered data fresh.
Image assets	staleWhileRevalidate	Fast image responses with background refresh.
Font assets	cacheFirst	Rarely changing font files cached aggressively.
/api/*	networkOnly	Avoids unsafe API response caching by default.

Security exclusions

These URL patterns are excluded from caching by default:

• /auth/*, /oauth/*, /sso/*
• /login, /logout, /signin, /signout, /signup
• /callback, /token, /verify
• /reset-password, /forgot-password, /session
• /api/auth/*
• /_next/image

<PWAHead />

PWAHead injects required PWA metadata and service worker registration behavior.

import PWAHead from "next-pwa-auto/head";

<PWAHead
  manifest="/manifest.webmanifest"
  themeColor="#000000"
  swRegisterPath="/_pwa/sw-register.js"
  enableSW
/>;

Props

Prop	Type	Default	Description
manifest	string	"/manifest.webmanifest"	Path to web manifest.
themeColor	string	"#000000"	Theme color meta value.
swRegisterPath	string	"/_pwa/sw-register.js"	SW registration script path.
enableSW	boolean	true in prod, false in dev	Force SW on/off.

usePWAUpdate hook

import usePWAUpdate from "next-pwa-auto/hooks";

export function UpdateBanner() {
  const { updateAvailable, update } = usePWAUpdate();

  if (!updateAvailable) return null;

  return <button onClick={update}>Update now</button>;
}

Hook return values

Property	Type	Description
updateAvailable	boolean	true when a new service worker is waiting.
update	() => void	Activates waiting SW and reloads the page.
registration	ServiceWorkerRegistration | null	Raw SW registration object.

Global runtime API

When SW registration is active, next-pwa-auto exposes a runtime helper:

window.__PWA_AUTO.update(); // trigger update check
window.__PWA_AUTO.skipWaiting(); // activate waiting SW
window.__PWA_AUTO.registration; // raw registration
window.__PWA_AUTO.version; // plugin version string

Generated files

After next build, these files are generated:

public/
|-- manifest.webmanifest
`-- _pwa/
    |-- icons/
    |   |-- icon-72x72.png
    |   |-- icon-96x96.png
    |   |-- icon-128x128.png
    |   |-- icon-144x144.png
    |   |-- icon-152x152.png
    |   |-- icon-192x192.png
    |   |-- icon-384x384.png
    |   |-- icon-512x512.png
    |   |-- icon-192x192-maskable.png
    |   `-- icon-512x512-maskable.png
    |-- offline.html
    `-- sw-register.js

Overrides and customization

Custom manifest merge

If public/manifest.json or public/manifest.webmanifest exists, its values are merged on top of the auto-generated manifest.

Custom offline page

If public/_offline.html exists, next-pwa-auto uses it as the offline fallback and copies it to public/_pwa/offline.html.

Custom source icon

Set a custom icon path via config:

icon: "./assets/my-logo.png";

If no icon is provided or found, a placeholder icon is generated automatically.

Deployment notes

• Works with output: "standalone" because assets are generated in public/.
• Works on Vercel with no extra routing setup for manifest/SW assets.
• HTTPS is required for service workers in production (localhost is exempt).

Development behavior

Service workers are disabled by default in development to avoid stale cache issues.

NEXT_PWA=1 next dev

Use this only when you explicitly want to test SW behavior in dev mode.