Astro SW

The integration accepts the path to your own authored service worker 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.

Installation

In your Astro project:

# 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:

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.

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.

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	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.

Background

This Astro integration library was developed to support the Caching strategy needs of Cozy -- the modern reading companion for the Web.