# Astro SW

[![Package information: NPM version](https://img.shields.io/npm/v/@ayco/astro-sw)](https://www.npmjs.com/package/@ayco/astro-sw)
[![Package information: NPM license](https://img.shields.io/npm/l/@ayco/astro-sw)](https://www.npmjs.com/package/@ayco/astro-sw)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@ayco/astro-sw)](#library-size)

The integration accepts the path to your own authored [service worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) and automatically injects dynamic variables such as `__assets` generated by Astro for caching.

It works on all Astro output options: `static`, `server`, or `hybrid`, and lets developers retain the flexibility for various [caching strategies](https://developer.chrome.com/docs/workbox/caching-strategies-overview/).

## Installation

In your [Astro](https://astro.build) project:

```bash
# if using npm
$ npm i -D @ayco/astro-sw

# if using pnpm
$ pnpm add -D @ayco/astro-sw
```

## Minimal Usage

Here's an example `astro.config.mjs` file:

```js
import { defineConfig } from "astro/config";
import serviceWorker from "@ayco/astro-sw";

export default defineConfig({
  integrations: [
    serviceWorker({
      path: "./src/sw.ts",
    })
  ]
});
```
For more options available, see the [API](#api).

## TypeScript support

We use `esbuild` to resolve service worker `imports` and build TS files! You can customize the build options by providing it to the `esbuild` configuration property.

```js
import { defineConfig } from "astro/config";
import serviceWorker from "@ayco/astro-sw";

export default defineConfig({
  integrations: [
    serviceWorker({
      path: "./src/sw.ts",
      esbuild: {
        minify: true
      }
    })
  ]
});
```

## Injected variables

The most important variable your service worker will have access to is `__assets`, which contains all routes and public assets that Astro includes in your build. Additionally, you will also get `__prefix` and `__version` you can use for naming & invalidating your Cache storage (useful for debugging purposes).

## API

The integration accepts a configuration object of type `ServiceWorkerConfig` with the following properties

| property | type | required? |  notes |
| --- | --- | --- | --- |
| path | string | required | path to your *own* service worker script; no surprises & easy debugging |
| assetCachePrefix | string | optional | cache storage name prefix |
| assetCacheVersionID | string | optional | cache storage name versioning; by default, a random UUID is used |
| customRoutes | string[] | optional | list of custom routes you want to be cached. Beware that non-existent routes that result to HTTP Error404 will cause the service worker to fail |
| excludeRoutes | string[] | optional | list of routes you want to be ignored/removed from assets |
| logAssets | boolean | optional | set to see a list of the assets found; defaults to false |
| esbuild | [BuildOptions](https://esbuild.github.io/api/) | optional | custom build options for your service worker script |

## Example sw.js

You can find an example service worker (`example_sw.js`) in the [repository](https://ayco.io/gh/astro-sw).

## Background

This Astro integration library was developed to support the Caching strategy needs of [Cozy](https://github.com/ayoayco/cozy) -- the modern reading companion for the Web.