@wells-nelson/build-tools 1.0.1 → 1.0.3

package/README.md

@@ -36,18 +36,38 @@ export default defineConfig(({ mode, command }) => ({
 }));
 ```
 
+### Content Security Policy
+
+`contentSecurityPolicy({ supabaseUrl })` returns SvelteKit `csp` options: hashes for SvelteKit's inline
+scripts and no other scripts, network access only to the app and its Supabase project (REST and
+Realtime), images from the app, `data:`/`blob:` and Google profile pictures. Pass `connect` / `img` for
+more sources.
+
+```js
+sveltekit({ csp: contentSecurityPolicy({ supabaseUrl: env.VITE_SUPABASE_URL }), ... })
+```
+
 ## Service worker (`@wells-nelson/build-tools/service-worker`)
 
 ```ts
 /// <reference types="@sveltejs/kit" />
-import { version } from '$app/env';
+import { dev, version } from '$app/env';
 import { assets, immutable } from '$app/manifest';
 import { self } from '$app/service-worker';
 import { registerAppShellCache } from '@wells-nelson/build-tools/service-worker';
 
-registerAppShellCache({ sw: self, version, files: [...immutable, ...assets], cachePrefix: 'my-app' });
+registerAppShellCache({ sw: self, version, dev, files: [...immutable, ...assets], cachePrefix: 'my-app' });
 ```
 
+Navigations go to the network first, so starting the app online always loads the latest deploy;
+offline they fall back to the cached shell. A new worker skips waiting and takes over open
+pages. `networkOnly` paths are never cached (default: SvelteKit's `_app/version.json`, so
+`updated` from `$app/state` notices new deploys). `dev` caches nothing.
+
+On activate a worker deletes only its own older caches (`<cachePrefix>-cache-*`). Give each app
+on an origin its own `cachePrefix`: GitHub Pages project sites of one user all share
+`https://<user>.github.io`.
+
 ## Templates
 
 `templates/deploy-pages.yml` (replace `__REPO__`) and `templates/manifest.webmanifest`.

package/dist/service-worker.d.ts

@@ -1,7 +1,9 @@
 /**
  * Offline-first app shell for a SvelteKit service worker. Everything the app needs is precached
- * on install; navigations fall back to the cached shell (the app root) when the network is
- * unavailable; cross-origin requests (Supabase, Google avatars) are left to the network.
+ * on install; navigations go to the network first (so starting the app online always
+ * loads the latest deploy) and fall back to the cached shell (the app root) offline. A new
+ * deploy's worker installs, skips waiting and takes over open pages straight away. Cross-origin
+ * requests (Supabase, Google avatars) are left to the network.
  *
  * ```ts
  * // src/service-worker/index.ts
@@ -27,21 +29,30 @@ export interface ServiceWorkerScopeLike {
 }
 export interface AppShellCacheOptions {
     sw: ServiceWorkerScopeLike;
-    /** Build version; each deploy gets a fresh cache and old ones are deleted. */
+    /** Build version; each deploy gets a fresh cache and this app's old ones are deleted. */
     version: string;
     /** Files to precache, relative to the scope (SvelteKit's `immutable` and `assets`). */
     files: Array<string | {
         path: string;
     }>;
-    /** Cache name prefix (default 'app'). */
+    /**
+     * Cache name prefix (default 'app'). Give every app on the same origin its own prefix: a worker
+     * only deletes caches named `<cachePrefix>-cache-*`, so apps sharing an origin keep each other's.
+     */
     cachePrefix?: string;
     /**
      * Development: cache nothing and delete what an earlier worker cached, so every code change
      * loads (a cache-first worker would otherwise keep serving stale dev modules).
      */
     dev?: boolean;
+    /**
+     * Paths (relative to the scope) that always go to the network and are never cached. Defaults
+     * to SvelteKit's `_app/version.json`, so its update check (`updated` in `$app/state`) sees
+     * new deploys instead of the first answer it ever cached.
+     */
+    networkOnly?: string[];
 }
-export declare function registerAppShellCache({ sw, version, files, cachePrefix, dev }: AppShellCacheOptions): {
+export declare function registerAppShellCache({ sw, version, files, cachePrefix, dev, networkOnly }: AppShellCacheOptions): {
     cacheName: null;
     precache: never[];
 } | {

package/dist/service-worker.js

@@ -1,7 +1,9 @@
 /**
  * Offline-first app shell for a SvelteKit service worker. Everything the app needs is precached
- * on install; navigations fall back to the cached shell (the app root) when the network is
- * unavailable; cross-origin requests (Supabase, Google avatars) are left to the network.
+ * on install; navigations go to the network first (so starting the app online always
+ * loads the latest deploy) and fall back to the cached shell (the app root) offline. A new
+ * deploy's worker installs, skips waiting and takes over open pages straight away. Cross-origin
+ * requests (Supabase, Google avatars) are left to the network.
  *
  * ```ts
  * // src/service-worker/index.ts
@@ -14,7 +16,7 @@
  * registerAppShellCache({ sw: self, version, dev, files: [...immutable, ...assets], cachePrefix: 'my-app' });
  * ```
  */
-export function registerAppShellCache({ sw, version, files, cachePrefix = 'app', dev = false }) {
+export function registerAppShellCache({ sw, version, files, cachePrefix = 'app', dev = false, networkOnly = ['_app/version.json'] }) {
     const CACHE = `${cachePrefix}-cache-${version}`;
     if (dev) {
         sw.addEventListener('install', (event) => event.waitUntil(sw.skipWaiting()));
@@ -31,6 +33,7 @@ export function registerAppShellCache({ sw, version, files, cachePrefix = 'app',
     const scope = new URL(sw.registration.scope);
     // The app root serves the SPA shell (index.html on GitHub Pages, the fallback page elsewhere).
     const SHELL = scope.href;
+    const NETWORK_ONLY = new Set(networkOnly.map((p) => new URL(p, scope).pathname));
     const PRECACHE = files.map((f) => new URL(typeof f === 'string' ? f : f.path, scope).href).concat(SHELL);
     sw.addEventListener('install', (event) => {
         event.waitUntil((async () => {
@@ -41,9 +44,12 @@ export function registerAppShellCache({ sw, version, files, cachePrefix = 'app',
     });
     sw.addEventListener('activate', (event) => {
         event.waitUntil((async () => {
-            for (const key of await caches.keys())
-                if (key !== CACHE)
+            // Only this app's older caches: other apps on the same origin (e.g. two GitHub Pages
+            // project sites under one user) keep theirs.
+            for (const key of await caches.keys()) {
+                if (key !== CACHE && key.startsWith(`${cachePrefix}-cache-`))
                     await caches.delete(key);
+            }
             await sw.clients.claim();
         })());
     });
@@ -52,7 +58,7 @@ export function registerAppShellCache({ sw, version, files, cachePrefix = 'app',
         if (request.method !== 'GET')
             return;
         const url = new URL(request.url);
-        if (url.origin !== scope.origin)
+        if (url.origin !== scope.origin || NETWORK_ONLY.has(url.pathname))
             return;
         if (request.mode === 'navigate') {
             event.respondWith((async () => {

package/dist/vite.d.ts

@@ -44,3 +44,25 @@ export declare function devJsonModule({ id, file, enabled }: {
     file: string;
     enabled: boolean;
 }): Plugin;
+/**
+ * SvelteKit `csp` options for an offline-first app on static hosting. SvelteKit adds a
+ * `<meta http-equiv="content-security-policy">` with hashes of its own inline scripts, so only
+ * the app's bundled scripts run: injected markup can't load or run other scripts. Network access
+ * is limited to the app's origin and its Supabase project (REST and Realtime); images also allow
+ * data/blob URLs and Google profile pictures. Styles allow inline (Svelte transitions use them).
+ *
+ * ```js
+ * sveltekit({ csp: contentSecurityPolicy({ supabaseUrl: env.VITE_SUPABASE_URL }), ... })
+ * ```
+ */
+export declare function contentSecurityPolicy({ supabaseUrl, connect, img }?: {
+    /** The project URL (`VITE_SUPABASE_URL`); without it any `*.supabase.co` project is allowed. */
+    supabaseUrl?: string;
+    /** Extra `connect-src` sources. */
+    connect?: string[];
+    /** Extra `img-src` sources. */
+    img?: string[];
+}): {
+    mode: "hash";
+    directives: Record<string, any[]>;
+};

package/dist/vite.js

@@ -80,3 +80,41 @@ export function devJsonModule({ id, file, enabled }) {
         }
     };
 }
+/**
+ * SvelteKit `csp` options for an offline-first app on static hosting. SvelteKit adds a
+ * `<meta http-equiv="content-security-policy">` with hashes of its own inline scripts, so only
+ * the app's bundled scripts run: injected markup can't load or run other scripts. Network access
+ * is limited to the app's origin and its Supabase project (REST and Realtime); images also allow
+ * data/blob URLs and Google profile pictures. Styles allow inline (Svelte transitions use them).
+ *
+ * ```js
+ * sveltekit({ csp: contentSecurityPolicy({ supabaseUrl: env.VITE_SUPABASE_URL }), ... })
+ * ```
+ */
+export function contentSecurityPolicy({ supabaseUrl, connect = [], img = [] } = {}) {
+    let supabase = ['https://*.supabase.co', 'wss://*.supabase.co'];
+    if (supabaseUrl) {
+        try {
+            const { host, protocol } = new URL(supabaseUrl);
+            supabase = [`${protocol}//${host}`, `${protocol === 'http:' ? 'ws' : 'wss'}://${host}`];
+        }
+        catch {
+            /* keep the wildcard */
+        }
+    }
+    // Typed loosely (`any[]`) so it fits SvelteKit's `CspDirectives` without depending on SvelteKit.
+    const directives = {
+        'default-src': ['self'],
+        'script-src': ['self'],
+        'style-src': ['self', 'unsafe-inline'],
+        'img-src': ['self', 'data:', 'blob:', 'https://*.googleusercontent.com', ...img],
+        'font-src': ['self'],
+        'connect-src': ['self', ...supabase, ...connect],
+        'worker-src': ['self'],
+        'manifest-src': ['self'],
+        'object-src': ['none'],
+        'base-uri': ['self'],
+        'form-action': ['self']
+    };
+    return { mode: 'hash', directives };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wells-nelson/build-tools",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Build and deployment tooling for Wells Nelson SvelteKit PWAs: postbuild, PWA icon generator, Vite config pieces, service worker, and templates.",
   "license": "MIT",
   "repository": {

package/templates/deploy-pages.yml

@@ -26,6 +26,9 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
+      # Nothing ships unless it type-checks and its tests pass.
+      - run: npm run check --if-present
+      - run: npm test --if-present
       - run: npm run build
         env:
           # Repository variables (Settings > Secrets and variables > Actions > Variables).