From 8c053f0d364537a5f0fcb5ba029b2a9b48f2a450 Mon Sep 17 00:00:00 2001 From: ayoayco Date: Sat, 17 Aug 2024 10:36:52 +0200 Subject: [PATCH] chore: update readme APIs and examples --- README.md | 47 ++++++++++++++++++++++++------ astro.config.mjs | 2 +- src/example_sw.ts => example_sw.js | 2 +- package.json | 2 +- 4 files changed, 41 insertions(+), 12 deletions(-) rename src/example_sw.ts => example_sw.js (98%) diff --git a/README.md b/README.md index 5329e0b..080f691 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,9 @@ [![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 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. The goal is to let devs retain the flexibility for various [caching strategies](https://developer.chrome.com/docs/workbox/caching-strategies-overview/). +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 @@ -18,9 +20,9 @@ $ npm i -D @ayco/astro-sw $ pnpm add -D @ayco/astro-sw ``` -## Usage +## Minimal Usage -Example `astro.config.mjs` +Here's an example `astro.config.mjs` file: ```js import { defineConfig } from "astro/config"; @@ -29,11 +31,36 @@ import serviceWorker from "@ayco/astro-sw"; export default defineConfig({ integrations: [ serviceWorker({ - path: "./src/sw.js", + 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 @@ -42,15 +69,17 @@ The integration accepts a configuration object of type `ServiceWorkerConfig` wit | 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; useful for debugging | -| assetCacheVersionID | string | optional | cache storage name versioning; by default, a random UUID is used but you can provide your own for easy debugging & invalidation | +| 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), and here's the [raw file](https://raw.githubusercontent.com/ayoayco/astro-sw/main/example_sw.js) too. +You can find an example service worker (`example_sw.js`) in the [repository](https://ayco.io/gh/astro-sw). -## Example project +## Background -This was developed to support the needs of [Cozy](https://github.com/ayoayco/cozy). \ No newline at end of file +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. \ No newline at end of file diff --git a/astro.config.mjs b/astro.config.mjs index 3553672..9a33df9 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -10,7 +10,7 @@ export default defineConfig({ site: 'https://ayo.ayco.io', integrations: [ serviceWorker({ - path: "./src/example_sw.ts", + path: "./example_sw.js", assetCachePrefix: 'cozy-reader', customRoutes: [ '/threads' diff --git a/src/example_sw.ts b/example_sw.js similarity index 98% rename from src/example_sw.ts rename to example_sw.js index 70fe866..0ad543c 100644 --- a/src/example_sw.ts +++ b/example_sw.js @@ -1,4 +1,4 @@ -import { log } from "./utils"; +import { log } from "./src/utils"; /** * Note: @ayco/astro-sw integration injects variables `__prefix`, `__version`, & `__assets` diff --git a/package.json b/package.json index d3c5199..212a7b0 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@ayco/astro-sw", "version": "0.7.0", - "description": "Simple Astro integration to use your own authored service-worker", + "description": "Simple Astro integration to use your own authored service worker", "homepage": "https://github.com/ayoayco/astro-sw", "repository": { "type": "git",