npm package: @ibash/next-service-worker
Description: Add a service worker powered by Workbox to your Next.js application
Author: Tate
Latest version: 0.0.4

# next-service-worker

<blockquote>Add a service worker powered by Workbox to your Next.js application</blockquote>

<br />

<a href="https://www.npmjs.com/package/next-service-worker">
  <img src="https://img.shields.io/npm/v/next-service-worker.svg">
</a>
<a href="https://github.com/tatethurston/next-service-worker/blob/master/LICENSE">
  <img src="https://img.shields.io/npm/l/next-service-worker.svg">
</a>
<a href="https://www.npmjs.com/package/next-service-worker">
  <img src="https://img.shields.io/npm/dy/next-service-worker.svg">
</a>

## What is this? 🧐

A minimal wrapper around [Workbox](https://developers.google.com/web/tools/workbox) to quickly add a [service worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) to your [Next.js](https://nextjs.org/) application. Get all of the power of workbox without needing to manage [webpack](https://webpack.js.org/) directly!

## Installation & Usage 📦

1. Add this package to your project:

   `yarn add next-service-worker`

2. Update your `next.config.js`:

   ```js
   const withServiceWorker = require("next-service-worker");

   module.exports = withServiceWorker({
     // next config here...

     serviceWorker: {
       // service worker config here...

       workbox: {
         // workbox config here...
       },
     },
   });
   ```

## API Overview 🛠

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
      <th>Type</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>enableInDevelopment</td>
<td>

Enable the service worker in local development.

Depending on your service worker configuration, this can be problematic for developer workflows where you end up serving outdated cached files.

If `false` then a placeholder service worker will be generated, which will immediately clear any previously installed service workers that may have been installed previously such as testing a production build locally.

Defaults to `false`. Recommended: `false` for general development, `true` for first time setup and when debugging your application's service worker.

</td>
<td>boolean | undefined</td>
</tr>
<tr>
  <td>enableWorkboxLogging</td>
<td>

Enable workbox logging.

Workbox logging is both very helpful and very chatty. By default, workbox will use the webpack mode to determine whether or not to enable workbox logging. When the mode is `production`, then logging is disabled. Otherwise, logging is enabled.

Setting this to `true` enables workbox logging when the webpack `mode` is set to `production`. Setting this to `false` will disable workbox logging, which is likely preferred when not debugging your servicer worker.

Note: This option is only relevant when using the service worker generated by workbox. It does not apply to the development service worker generated when `enableInDevelopment` is `false`, or if you supply your own service worker via workbox's `swSrc` field.

Defaults to `unset`, falling back on the workbox behavior. Recommended: `false` for general development, `true` for first time setup and when debugging your application's service worker.

</td>
  <td>boolean | undefined</td>
</tr>
<tr>
  <td>registration.autoRegister</td>
<td>

Autoregister the service worker.

If `false`, then the application must initialize the service worker by invoking `register`. Set this to `false` if you'd like to take control over when you service worker is initialized. You'll then need to add something like the following to your application:

```javascript
import { Workbox } from "workbox-window";

if ("serviceWorker" in navigator) {
  const wb = new Workbox("/path-to-your-service-worker.js");
  wb.register();
}
```

Defaults to `true`. Recommended: `true`.

</td>
</td>
  <td>boolean | undefined</td>
</tr>

<tr>
  <td>registration.path</td>
<td>

The [registration path](https://developers.google.com/web/ilt/pwa/introduction-to-service-worker#registration_and_scope) tells the browser where your service worker is located.

Defaults to `/service-worker.js`.

</td>
</td>
  <td>string | undefined</td>
</tr>
<tr>
  <td>registration.scope</td>
<td>

The [scope](https://developers.google.com/web/ilt/pwa/introduction-to-service-worker#registration_and_scope) of the service worker determines which files the service worker controls, in other words, from which path the service worker will intercept requests. The default scope is the location of the service worker file, and extends to all directories below. So if service-worker.js is located in the root directory, the service worker will control requests from all files at this domain.

Defaults to your [next.config.js basePath](https://nextjs.org/docs/api-reference/next.config.js/basepath).

</td>
</td>
  <td>string | undefined</td>
</tr>
<tr>
  <td>workbox</td>
<td>

Options passed to `worbox-webpack-plugin`. See all available configuration options [here](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin).

Defaults to `GenerateSW` which will generate a service worker with the workbox runtime included.

</td>
  <td>InjectManifestOptions | GenerateSWOptions</td>
</tr>
  </tbody>
</table>

## Examples 🚀

Check out the [next-service-worker-example](https://github.com/tatethurston/next-service-worker/blob/master/examples/next-service-worker-example/). The only change from the default NextJS setup is the addition of `next.config.js`!

## Common Service Worker Pitfalls ⚠️

You must serve your next application over HTTPS in production environments. [Service Workers must be served from the site's origin over HTTPS](https://developers.google.com/web/fundamentals/primers/service-workers).

Most browsers make special case `localhost`, so this is generally not necessary during local development. HTTPS is _not_ handled by this library.

The service worker origin constraint means that the service worker can not control `mysite.com` if it was served from a subdomain such as `mycdn.mysite.com`. If you serve from Next's public folder, things will work out of the box. If you move Next's public folder contents to a CDN and serve the service worker from that CDN additional configuration may be necessary.

## Related Projects

- [Next PWA](https://www.npmjs.com/package/next-pwa)

- [Next Offline](https://github.com/hanford/next-offline)

## Highlights

🪠 Handles the NextJS specific plumbing for you so you can focus on your application!

## Contributing 👫

PR's and issues welcomed! For more guidance check out [CONTRIBUTING.md](https://github.com/tatethurston/next-service-worker/blob/master/CONTRIBUTING.md)

## Licensing 📃

See the project's [MIT License](https://github.com/tatethurston/next-service-worker/blob/master/LICENSE).