Astro SW

Use your own authored service worker with Astro.

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

Background

This integration was originally developed to support the Caching strategy needs of Cozy -- the modern reading companion for the Web. You can find an example service worker in the repository.

There is a work in progress adding presets for using common caching strategies and customizing the behavior of the service worker via config options. This aims to reduce the need for writing the service worker script by hand for most use cases.

Get in touch:

1. Chat via Discord: Ayo's Projects
2. Submit tickets via SourceHut todo
3. Start a GitHub discussion
4. Email me: [email protected]

Installation

In your Astro project:

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

# if using pnpm
$ pnpm add @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).

eslint globals

Because of the injected variables not being defined in your script, you might get eslint errors for the undefined variables when you have the no-undef rule. To prevent this, you can use our exported globals object in your eslint config as follows:

import astroSwGlobals from "@ayco/astro-sw/globals";

export default [
  {
    languageOptions: {
      globals: {
        ...astroSwGlobals,
      },
    },
  },
  // add more generic rule sets here, such as:
  // jsPlugin.configs.recommended,
];

Registration Hooks

Hooks are provided for adding custom logic that triggers in various service worker registration events.

The following properties are available for the registrationHooks configuration:

1. installing - when the registration is 'installing'
2. waiting - when the registration is 'waiting'
3. active - when the registration is 'active'
4. error - when the registration throws an error
5. unsupported - when the service workers are unsupported
6. afterRegistration - after the registration succeeds

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

export default defineConfig({
  integrations: [
    serviceWorker({
      path: "./src/sw.ts",
      registrationHooks: {
        afterRegistration: async () => {
          const sw = await navigator.serviceWorker.getRegistration();
          console.log(">>> registrered", sw);
        },
        installing: () => console.log("installing..."),
        waiting: () => console.log("waiting..."),
        active: () => console.log("active..."),
        error: (error) => console.error(error),
        unsupported: () => console.log(":("),
      },
    }),
  ],
});

API

The integration accepts a configuration object 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
registrationHooks	object	optional	provide callbacks for various registration events; see section on Registration Hooks