next-pwa-auto

Appearance

Get Started ​

This guide walks you through the fastest way to set up next-pwa-auto.

From your Next.js project root, run:

bash
npx next-pwa-auto init

init is the recommended setup path. It can:

  • Detect router type (App Router or Pages Router)
  • Configure next.config.* with withPWAAuto()
  • Add <PWAHead /> to your root layout
  • Help you choose an icon (or keep placeholder generation)
  • Run follow-up checks with doctor

Useful init modes ​

bash
# Non-interactive setup with defaults
npx next-pwa-auto init --skip

# Re-run setup even if already configured
npx next-pwa-auto init --skip --force

Health check ​

After setup (or after manual changes), run:

bash
npx next-pwa-auto doctor

This validates common issues such as config wiring, icon availability, and generated PWA output.

Manual setup (optional) ​

1. Install ​

bash
# npm
npm install next-pwa-auto

# yarn
yarn add next-pwa-auto

# pnpm
pnpm add next-pwa-auto

# bun
bun add next-pwa-auto

2. Wrap your Next.js config ​

Use withPWAAuto() to enable automatic PWA generation at build time.

js
// next.config.js (CommonJS)
const withPWAAuto = require("next-pwa-auto").default;

/** @type {import("next").NextConfig} */
const nextConfig = {};

module.exports = withPWAAuto()(nextConfig);
ts
// next.config.mjs / next.config.ts (ESM)
import withPWAAuto from "next-pwa-auto";

const nextConfig = {};

export default withPWAAuto()(nextConfig);

3. Add <PWAHead /> ​

<PWAHead /> injects the manifest link, theme color tags, and service worker registration logic.

tsx
// app/layout.tsx (App Router)
import PWAHead from "next-pwa-auto/head";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <PWAHead />
      </head>
      <body>{children}</body>
    </html>
  );
}
tsx
// pages/_app.tsx (Pages Router)
import PWAHead from "next-pwa-auto/head";

export default function App({ Component, pageProps }) {
  return (
    <>
      <PWAHead />
      <Component {...pageProps} />
    </>
  );
}

4. Provide an app icon (optional) ​

Add one of these files to public/:

  • icon.svg
  • icon.png
  • logo.svg
  • logo.png
  • favicon.svg
  • favicon.png

A 512x512 PNG works best. If no icon is found, next-pwa-auto generates a placeholder icon automatically.

5. Build your app ​

bash
next build

On build, next-pwa-auto generates:

  • public/manifest.webmanifest
  • public/_pwa/icons/*
  • public/_pwa/offline.html
  • public/_pwa/sw-register.js

Next ​

  • Usage - Full config options, hooks, and CLI reference
  • FAQ - Common setup and deployment questions
  • GitHub Repository - Source code and issue tracker

Released under the MIT License.

Copyright (c) 2026 next-pwa-auto