next-pwa

@ducanh2912/next-pwa is a package designed to enable Progressive Web App (PWA) capabilities within Next.js applications, powered by Workbox.

Note for new projects: This package is the predecessor to @serwist/next. If you are starting a new project, it is recommended to use Serwist instead.

By default, next-pwa handles service worker registration automatically. However, you can gain more control by manually managing the registration process and listening to lifecycle events. This approach allows you to:

1. Control Registration: Decide exactly when the service worker is registered instead of letting it happen automatically.
2. Handle Lifecycle Events: Add event listeners to react to service worker changes.
3. Prompt for Updates: Implement a pattern to prompt users to reload the page when a new version of the service worker is available (e.g., using Workbox advanced recipes).

By default, @ducanh2912/next-pwa uses a specific set of regex patterns to determine which files are precached. The default exclusion pattern is:

[//_next/static/.*(?<!\.p)\.woff2/, /^\.map$/, /^manifest.*\.js$/]

Excluded by default:

• Fonts: next/font subsets are excluded to prevent the precache manifest from becoming too large.
• .map files: Source maps are excluded as they are not required by end-users.
• .manifest.*.js files: Webpack-generated manifests (including the precache manifest itself) are excluded to avoid redundant or unnecessary caching.

@ducanh2912/next-pwa provides built-in offline capabilities:

• Automatic Precaching: JavaScript, CSS, and image assets are precached out of the box.
• Runtime Caching: Pages are cached automatically as you visit them.
• Offline Fallbacks: You can explicitly enable offline fallbacks to provide custom handling for assets or pages that have not yet been cached.

To run the documentation site locally, follow these steps from the root folder of the project:

1. Install dependencies using pnpm i.
2. Build the packages using pnpm build.
3. Navigate to the docs directory and start the development server with pnpm dev.
4. Access the documentation at http://localhost:3000.

Note: These commands must be run in the root folder of the repository.

pnpm i
pnpm build
cd docs && pnpm dev

To enable PWA support in your Next.js project, wrap your next.config.js with the withPWA function exported as the default from @ducanh2912/next-pwa. At a minimum, you should provide the dest option to specify the directory where the service worker files will be generated (typically public).

const withPWA = require("@ducanh2912/next-pwa").default({
  dest: "public",
});

module.exports = withPWA({
  // Your Next.js config
});

If you are not using Next.js's built-in server, you can use a custom server (like fastify) to serve your PWA assets. The custom server must be configured to serve sw.js and precache scripts statically from the public directory to ensure full offline support and proper PWA functionality.

Note: It is still recommended to use Next.js's built-in server whenever possible.

# To run the custom server example:
cd examples/custom-server
pnpm build
pnpm start

When using next-pwa, the build process generates service worker files and precache manifests in the public directory. To prevent these generated files from being committed to your version control system, add the following patterns to your .gitignore file:

**/public/precache.*.js
**/public/sw.js

You can bootstrap a new Next.js project using the custom worker example template with any of the following package managers:

# Using npx
npx create-next-app --example https://github.com/DuCanhGH/next-pwa/tree/master/examples/custom-worker custom-worker-app

# Using yarn
yarn create next-app --example https://github.com/DuCanhGH/next-pwa/tree/master/examples/custom-worker custom-worker-app

# Using pnpm
pnpm create next-app --example https://github.com/DuCanhGH/next-pwa/tree/master/examples/custom-worker custom-worker-app

# Using bun
bun create next-app --example https://github.com/DuCanhGH/next-pwa/tree/master/examples/custom-worker custom-worker-app

You can bootstrap a new Next.js application using the lifecycle and register workflow pattern by using the create-next-app command with the specific example template from this repository.

npx create-next-app --example https://github.com/DuCanhGH/next-pwa/tree/master/examples/lifecycle lifecycle-app

To cache assets during client-side (front-end) navigation in Next.js, you no longer need custom implementation code. Since version 5.2.1 of @ducanh2912/next-pwa, you can enable this behavior directly via the configuration object by setting cacheOnFrontEndNav to true.

// next.config.js
const withPWA = require('@ducanh2912/next-pwa')({
  cacheOnFrontEndNav: true,
  // other config options
})

module.exports = withPWA({
  // your next.config.js config
})