@farm.js/pwa 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,97 @@
+# @farm.js/pwa
+
+Installable, offline-aware Progressive Web Apps for Farm.js. The plugin generates a route-aware
+service worker during the production build and registers it through Farm's browser plugin lifecycle.
+
+Farm.js is currently in beta.
+
+## Install
+
+```bash
+pnpm add @farm.js/pwa
+```
+
+## Configure
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { pwa } from "@farm.js/pwa";
+
+export default defineConfig({
+  plugins: [
+    pwa({
+      offline: "/offline",
+      cache: "recommended",
+    }),
+  ],
+});
+```
+
+Create `src/app/offline/page.tsx` as a static route and define application metadata in
+`src/app/manifest.ts`. Farm already serves that manifest at `/manifest.webmanifest`, so the plugin
+does not duplicate it.
+
+## Short cache configuration
+
+`recommended` precaches emitted static pages and uses SWR for public same-origin images:
+
+```ts
+pwa({
+  offline: "/offline",
+  cache: "recommended",
+});
+```
+
+The explicit short form is:
+
+```ts
+pwa({
+  cache: {
+    staticRoutes: true,
+    images: "swr",
+  },
+});
+```
+
+`swr` means stale while revalidate. A cached image is returned immediately while the worker fetches
+and stores a newer response in the background. The default keeps 100 entries fresh for 30 days.
+
+Override those limits only when needed:
+
+```ts
+pwa({
+  cache: {
+    staticRoutes: ["/", "/pricing"],
+    images: {
+      strategy: "swr",
+      limit: 200,
+      ttl: "7d",
+    },
+  },
+});
+```
+
+## Updates
+
+`update: "prompt"` is the default. The plugin dispatches `farm:pwa:update-available` when a new
+worker is waiting:
+
+```ts
+window.addEventListener("farm:pwa:update-available", (event) => {
+  const { applyUpdate } = (event as CustomEvent).detail;
+  showUpdateButton(applyUpdate);
+});
+```
+
+The same action is available as `window.__FARM_PWA__?.applyUpdate()`. Use `update: "auto"` only when
+an automatic reload cannot discard unsaved user work.
+
+## Safety boundaries
+
+The generated worker only intercepts `GET` requests. It never caches cross-origin traffic,
+mutations, API requests as pages, server actions, integrations, or workflows. Image requests with
+an `Authorization` header and responses marked `private`, `no-store`, or `no-cache` are not stored.
+Treat `images: "swr"` as an opt-in for public images, not private account media.
+
+Service workers register only in production. Test the complete behavior with `farm build` and a
+production server over HTTPS or localhost.

package/dist/build.d.ts

@@ -0,0 +1,29 @@
+import type { ResolvedPwaOptions } from "./config.js";
+export interface PwaBuildInput {
+    outputDir: string;
+    publicDir?: string;
+    preset: string;
+    basePath: string;
+    options: ResolvedPwaOptions;
+}
+export interface PwaBuildResult {
+    workerPath: string;
+    workerUrl: string;
+    precacheUrls: string[];
+    staticRoutes: Record<string, string>;
+    cacheId: string;
+}
+export declare function writePwaBuildArtifacts(input: PwaBuildInput): Promise<PwaBuildResult>;
+export interface GenerateServiceWorkerOptions {
+    cacheId: string;
+    precacheUrls: string[];
+    staticRoutes: Record<string, string>;
+    offlineRoute: string | false;
+    update: "prompt" | "auto";
+    images: ResolvedPwaOptions["cache"]["images"];
+}
+export declare function generateServiceWorker(options: GenerateServiceWorkerOptions): string;
+export declare function resolvePwaPublicDir(outputDir: string, preset: string): string;
+export declare function normalizeBasePath(value: string | undefined): string;
+export declare function withBasePath(route: string, basePath: string): string;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA0E1F;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7B,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC;CAC/C;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAkJnF;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK7E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGnE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQpE"}

package/dist/build.js

@@ -0,0 +1,279 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const PRECACHE_EXTENSIONS = new Set([
+    ".css",
+    ".js",
+    ".mjs",
+    ".otf",
+    ".ttf",
+    ".wasm",
+    ".webmanifest",
+    ".woff",
+    ".woff2",
+]);
+export async function writePwaBuildArtifacts(input) {
+    const publicDir = input.publicDir ?? resolvePwaPublicDir(input.outputDir, input.preset);
+    const files = await walkFiles(publicDir);
+    const staticRouteFiles = resolveStaticRouteFiles(files);
+    const basePath = normalizeBasePath(input.basePath);
+    const workerRelativePath = path.posix.join(basePath.replace(/^\//, ""), "sw.js");
+    const selectedRoutes = selectStaticRoutes(staticRouteFiles, input.options.cache.staticRoutes, basePath);
+    const configuredOfflineRoute = input.options.offline;
+    const offlineRoute = configuredOfflineRoute
+        ? withBasePath(configuredOfflineRoute, basePath)
+        : false;
+    if (offlineRoute && configuredOfflineRoute) {
+        const emittedOfflineFile = staticRouteFiles[configuredOfflineRoute] ?? staticRouteFiles[offlineRoute];
+        if (!emittedOfflineFile) {
+            throw new Error(`[farm:pwa] Offline route ${JSON.stringify(input.options.offline)} was not emitted as a static page. ` +
+                "Create that page as a static Farm route so it can be precached.");
+        }
+        selectedRoutes[offlineRoute] = emittedOfflineFile;
+    }
+    const assetFiles = files.filter((file) => file !== workerRelativePath && PRECACHE_EXTENSIONS.has(path.extname(file).toLowerCase()));
+    const precacheFiles = [...new Set([...assetFiles, ...Object.values(selectedRoutes)])].sort();
+    const precacheUrls = precacheFiles.map(toPublicUrl);
+    const fileHashes = await Promise.all(precacheFiles.map(async (file) => {
+        const content = await readFile(path.join(publicDir, file));
+        return `${file}:${createHash("sha256").update(content).digest("hex")}`;
+    }));
+    const cacheId = createHash("sha256")
+        .update(JSON.stringify({
+        files: fileHashes,
+        routes: selectedRoutes,
+        offlineRoute,
+        update: input.options.update,
+        images: input.options.cache.images,
+    }))
+        .digest("hex")
+        .slice(0, 16);
+    const workerPath = path.join(publicDir, ...workerRelativePath.split("/"));
+    await mkdir(path.dirname(workerPath), { recursive: true });
+    await writeFile(workerPath, generateServiceWorker({
+        cacheId,
+        precacheUrls,
+        staticRoutes: selectedRoutes,
+        offlineRoute,
+        update: input.options.update,
+        images: input.options.cache.images,
+    }));
+    return {
+        workerPath,
+        workerUrl: withBasePath("/sw.js", basePath),
+        precacheUrls,
+        staticRoutes: selectedRoutes,
+        cacheId,
+    };
+}
+export function generateServiceWorker(options) {
+    const routeFiles = Object.fromEntries(Object.entries(options.staticRoutes).map(([route, file]) => [route, toPublicUrl(file)]));
+    const offlineFile = options.offlineRoute ? (routeFiles[options.offlineRoute] ?? null) : null;
+    return `/* Generated by @farm.js/pwa. */
+const PRECACHE = ${JSON.stringify(`farm-pwa-precache-${options.cacheId}`)};
+const IMAGE_CACHE = "farm-pwa-images-v1";
+const PRECACHE_URLS = ${JSON.stringify(options.precacheUrls)};
+const PRECACHE_PATHS = new Set(PRECACHE_URLS.map((value) => new URL(value, self.location.origin).pathname));
+const STATIC_ROUTES = ${JSON.stringify(routeFiles)};
+const OFFLINE_FILE = ${JSON.stringify(offlineFile)};
+const IMAGE_OPTIONS = ${JSON.stringify(options.images)};
+
+self.addEventListener("install", (event) => {
+  event.waitUntil((async () => {
+    const cache = await caches.open(PRECACHE);
+    await cache.addAll(PRECACHE_URLS);
+    ${options.update === "auto" ? "await self.skipWaiting();" : ""}
+  })());
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil((async () => {
+    const names = await caches.keys();
+    await Promise.all(names
+      .filter((name) => name.startsWith("farm-pwa-precache-") && name !== PRECACHE)
+      .map((name) => caches.delete(name)));
+    await self.clients.claim();
+  })());
+});
+
+self.addEventListener("message", (event) => {
+  if (event.data?.type === "FARM_PWA_SKIP_WAITING") void self.skipWaiting();
+});
+
+self.addEventListener("fetch", (event) => {
+  const request = event.request;
+  if (request.method !== "GET") return;
+
+  const url = new URL(request.url);
+  if (url.origin !== self.location.origin) return;
+
+  if (request.mode === "navigate") {
+    event.respondWith(handleNavigation(request, url));
+    return;
+  }
+
+  if (PRECACHE_PATHS.has(url.pathname)) {
+    event.respondWith(cacheFirst(request));
+    return;
+  }
+
+  if (IMAGE_OPTIONS && request.destination === "image") {
+    event.respondWith(staleWhileRevalidateImage(request));
+  }
+});
+
+async function cacheFirst(request) {
+  const cache = await caches.open(PRECACHE);
+  return (await cache.match(request, { ignoreSearch: true })) ?? fetch(request);
+}
+
+async function handleNavigation(request, url) {
+  const staticFile = STATIC_ROUTES[normalizePathname(url.pathname)];
+  if (staticFile) {
+    const cached = await caches.match(staticFile, { cacheName: PRECACHE });
+    if (cached) return cached;
+  }
+
+  try {
+    return await fetch(request);
+  } catch (error) {
+    if (OFFLINE_FILE) {
+      const fallback = await caches.match(OFFLINE_FILE, { cacheName: PRECACHE });
+      if (fallback) return fallback;
+    }
+    throw error;
+  }
+}
+
+async function staleWhileRevalidateImage(request) {
+  if (request.headers.has("authorization")) return fetch(request);
+
+  const cache = await caches.open(IMAGE_CACHE);
+  const cached = await cache.match(request);
+  const cachedAt = Number(cached?.headers.get("x-farm-pwa-cached-at") || 0);
+  const fresh = cached && Date.now() - cachedAt <= IMAGE_OPTIONS.ttlMs;
+  const update = fetchAndCacheImage(request, cache);
+
+  if (fresh) {
+    void update.catch(() => undefined);
+    return cached;
+  }
+
+  try {
+    return await update;
+  } catch (error) {
+    if (cached) return cached;
+    throw error;
+  }
+}
+
+async function fetchAndCacheImage(request, cache) {
+  const response = await fetch(request);
+  if (!isPublicCacheableImage(response)) return response;
+
+  const headers = new Headers(response.headers);
+  headers.set("x-farm-pwa-cached-at", String(Date.now()));
+  const stored = new Response(response.clone().body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+  await cache.put(request, stored);
+  await trimImageCache(cache, IMAGE_OPTIONS.limit);
+  return response;
+}
+
+function isPublicCacheableImage(response) {
+  if (!response.ok || response.type === "opaque") return false;
+  const policy = (response.headers.get("cache-control") || "").toLowerCase();
+  return !policy.includes("private") && !policy.includes("no-store") && !policy.includes("no-cache");
+}
+
+async function trimImageCache(cache, limit) {
+  const keys = await cache.keys();
+  if (keys.length <= limit) return;
+
+  const entries = await Promise.all(keys.map(async (request) => {
+    const response = await cache.match(request);
+    return {
+      request,
+      cachedAt: Number(response?.headers.get("x-farm-pwa-cached-at") || 0),
+    };
+  }));
+  entries.sort((left, right) => left.cachedAt - right.cachedAt);
+  await Promise.all(entries.slice(0, entries.length - limit).map(({ request }) => cache.delete(request)));
+}
+
+function normalizePathname(pathname) {
+  if (pathname === "/") return pathname;
+  return pathname.replace(/\\/+$/, "");
+}
+`;
+}
+export function resolvePwaPublicDir(outputDir, preset) {
+    return path.join(outputDir, preset === "vercel" || preset === "vercel-edge" ? "static" : "public");
+}
+export function normalizeBasePath(value) {
+    if (!value || value === "/")
+        return "/";
+    return `/${value.replace(/^\/+|\/+$/g, "")}`;
+}
+export function withBasePath(route, basePath) {
+    const normalizedBase = normalizeBasePath(basePath);
+    const normalizedRoute = route === "/" ? "/" : `/${route.replace(/^\/+|\/+$/g, "")}`;
+    if (normalizedBase === "/")
+        return normalizedRoute;
+    if (normalizedRoute === normalizedBase || normalizedRoute.startsWith(`${normalizedBase}/`)) {
+        return normalizedRoute;
+    }
+    return normalizedRoute === "/" ? normalizedBase : `${normalizedBase}${normalizedRoute}`;
+}
+async function walkFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = await Promise.all(entries.map(async (entry) => {
+        const relative = entry.name;
+        if (entry.isDirectory()) {
+            return (await walkFiles(path.join(root, entry.name))).map((file) => path.posix.join(relative, file));
+        }
+        return entry.isFile() ? [relative] : [];
+    }));
+    return files.flat().sort();
+}
+function resolveStaticRouteFiles(files) {
+    const routes = {};
+    for (const file of files) {
+        if (path.extname(file).toLowerCase() !== ".html")
+            continue;
+        const normalized = file.replace(/\\/g, "/");
+        const withoutIndex = normalized.replace(/(?:^|\/)index\.html$/, "");
+        const route = withoutIndex
+            ? `/${withoutIndex.replace(/\.html$/, "").replace(/^\/+|\/+$/g, "")}`
+            : "/";
+        routes[route] = normalized;
+    }
+    return routes;
+}
+function selectStaticRoutes(emitted, configured, basePath) {
+    if (configured === false)
+        return {};
+    if (configured === true) {
+        return Object.fromEntries(Object.entries(emitted).map(([route, file]) => [withBasePath(route, basePath), file]));
+    }
+    const selected = {};
+    for (const requested of configured) {
+        const route = withBasePath(requested, basePath);
+        const emittedFile = emitted[requested] ?? emitted[route];
+        if (!emittedFile) {
+            throw new Error(`[farm:pwa] Static route ${JSON.stringify(requested)} was not found in the production output.`);
+        }
+        selected[route] = emittedFile;
+    }
+    return selected;
+}
+function toPublicUrl(file) {
+    return `/${file
+        .replace(/\\/g, "/")
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/")}`;
+}

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+export type PwaDuration = number | `${number}${"s" | "m" | "h" | "d" | "w"}`;
+export interface PwaImageCacheOptions {
+    /** Show the cached image immediately and refresh it in the background. */
+    strategy: "swr";
+    /** Maximum number of public image responses retained in Cache Storage. */
+    limit?: number;
+    /** How long a cached image remains fresh. Numbers are milliseconds. */
+    ttl?: PwaDuration;
+}
+export type PwaImageCache = boolean | "swr" | PwaImageCacheOptions;
+export interface PwaCacheOptions {
+    /** Precache every emitted static page, selected routes, or no static pages. */
+    staticRoutes?: boolean | string[];
+    /** Opt in to same-origin public image caching. */
+    images?: PwaImageCache;
+}
+export interface PwaPluginOptions {
+    /** Set false to keep the plugin registered without emitting or registering a worker. */
+    enabled?: boolean;
+    /** Static route to serve after an offline navigation misses the cache. */
+    offline?: string | false;
+    /** How a waiting service worker becomes active. */
+    update?: "prompt" | "auto";
+    /** Recommended caching, custom caching, or build assets only. */
+    cache?: "recommended" | PwaCacheOptions | false;
+}
+export interface ResolvedPwaImageCacheOptions {
+    strategy: "swr";
+    limit: number;
+    ttlMs: number;
+}
+export interface ResolvedPwaOptions {
+    enabled: boolean;
+    offline: string | false;
+    update: "prompt" | "auto";
+    cache: {
+        staticRoutes: boolean | string[];
+        images: ResolvedPwaImageCacheOptions | false;
+    };
+}
+export declare function resolvePwaOptions(options?: PwaPluginOptions): ResolvedPwaOptions;
+export declare function parsePwaDuration(value: PwaDuration): number;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,EAAE,KAAK,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,GAAG,CAAC,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,oBAAoB,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzB,mDAAmD;IACnD,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,iEAAiE;IACjE,KAAK,CAAC,EAAE,aAAa,GAAG,eAAe,GAAG,KAAK,CAAC;CACjD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE;QACL,YAAY,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;QACjC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAAC;KAC9C,CAAC;CACH;AAKD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,gBAAqB,GAAG,kBAAkB,CAuBpF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA0B3D"}

package/dist/config.js

@@ -0,0 +1,81 @@
+const DEFAULT_IMAGE_LIMIT = 100;
+const DEFAULT_IMAGE_TTL = "30d";
+export function resolvePwaOptions(options = {}) {
+    const cache = options.cache ?? "recommended";
+    const customCache = typeof cache === "object" ? cache : undefined;
+    return {
+        enabled: options.enabled !== false,
+        offline: normalizeRoute(options.offline ?? false, "offline"),
+        update: options.update ?? "prompt",
+        cache: {
+            staticRoutes: cache === "recommended"
+                ? true
+                : cache === false
+                    ? false
+                    : normalizeStaticRoutes(customCache?.staticRoutes ?? false),
+            images: cache === "recommended"
+                ? resolveImageCache("swr")
+                : cache === false
+                    ? false
+                    : resolveImageCache(customCache?.images ?? false),
+        },
+    };
+}
+export function parsePwaDuration(value) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new TypeError("PWA cache ttl must be a positive finite number");
+        }
+        return value;
+    }
+    const match = /^(\d+(?:\.\d+)?)(s|m|h|d|w)$/.exec(value);
+    if (!match) {
+        throw new TypeError('PWA cache ttl must use a duration such as "30s", "5m", "2h", or "30d"');
+    }
+    const amount = Number(match[1]);
+    if (amount <= 0) {
+        throw new TypeError("PWA cache ttl must be a positive duration");
+    }
+    const multiplier = {
+        s: 1_000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+        w: 604_800_000,
+    }[match[2]];
+    return amount * multiplier;
+}
+function resolveImageCache(value) {
+    if (value === false)
+        return false;
+    if (value !== true && value !== "swr" && value.strategy !== "swr") {
+        throw new TypeError('PWA image cache strategy must be "swr"');
+    }
+    const configured = typeof value === "object" ? value : undefined;
+    const limit = configured?.limit ?? DEFAULT_IMAGE_LIMIT;
+    if (!Number.isInteger(limit) || limit <= 0) {
+        throw new TypeError("PWA image cache limit must be a positive integer");
+    }
+    return {
+        strategy: "swr",
+        limit,
+        ttlMs: parsePwaDuration(configured?.ttl ?? DEFAULT_IMAGE_TTL),
+    };
+}
+function normalizeStaticRoutes(value) {
+    if (!Array.isArray(value))
+        return value;
+    return [...new Set(value.map((route) => normalizeRoute(route, "static route")))];
+}
+function normalizeRoute(value, label) {
+    if (value === false)
+        return false;
+    const route = value.trim();
+    if (!route.startsWith("/")) {
+        throw new TypeError(`PWA ${label} must start with "/"`);
+    }
+    if (route.includes("?") || route.includes("#")) {
+        throw new TypeError(`PWA ${label} cannot contain a query string or fragment`);
+    }
+    return route === "/" ? route : route.replace(/\/+$/, "");
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { type PwaCacheOptions, type PwaDuration, type PwaImageCache, type PwaImageCacheOptions, type PwaPluginOptions } from "./config.js";
+export type { PwaCacheOptions, PwaDuration, PwaImageCache, PwaImageCacheOptions, PwaPluginOptions };
+export interface FarmPwaBrowserRuntime {
+    registration: ServiceWorkerRegistration;
+    applyUpdate(): void;
+}
+export interface FarmPwaUpdateEventDetail {
+    registration: ServiceWorkerRegistration;
+    applyUpdate(): void;
+}
+declare global {
+    interface Window {
+        /** Browser runtime installed by `@farm.js/pwa`. */
+        __FARM_PWA__?: FarmPwaBrowserRuntime;
+    }
+}
+/**
+ * Generate and register a route-aware service worker for a Farm application.
+ * Build assets are always precached. Optional page and image caching stays
+ * constrained to safe GET navigation and same-origin image requests.
+ */
+export declare function pwa(options?: PwaPluginOptions): import("@farm.js/core/plugin").FarmPlugin<undefined, Record<string, never>, {
+    cleanup(): void;
+} | undefined, {
+    enabled: boolean;
+    workerUrl: string;
+    scope: string;
+    update: "prompt" | "auto";
+}, unknown, false>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,CAAC;AAEpG,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,yBAAyB,CAAC;IACxC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,yBAAyB,CAAC;IACxC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,mDAAmD;QACnD,YAAY,CAAC,EAAE,qBAAqB,CAAC;KACtC;CACF;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,OAAO,GAAE,gBAAqB;;;;;;;mBAoIjD"}

package/dist/index.js

@@ -0,0 +1,142 @@
+import { definePlugin } from "@farm.js/core/plugin";
+import { normalizeBasePath, withBasePath, writePwaBuildArtifacts } from "./build.js";
+import { resolvePwaOptions, } from "./config.js";
+/**
+ * Generate and register a route-aware service worker for a Farm application.
+ * Build assets are always precached. Optional page and image caching stays
+ * constrained to safe GET navigation and same-origin image requests.
+ */
+export function pwa(options = {}) {
+    const resolved = resolvePwaOptions(options);
+    let configuredBasePath = "/";
+    let configuredOutputDir = ".farm/.output";
+    const publicConfig = {
+        enabled: resolved.enabled,
+        workerUrl: "/sw.js",
+        scope: "/",
+        update: resolved.update,
+    };
+    return definePlugin({
+        name: "farm:pwa",
+        configure(config) {
+            const basePath = normalizeBasePath(config.basePath);
+            configuredBasePath = basePath;
+            configuredOutputDir = `${config.root ?? "."}/.farm/.output`;
+            publicConfig.workerUrl = withBasePath("/sw.js", basePath);
+            publicConfig.scope = basePath === "/" ? "/" : `${basePath}/`;
+        },
+        build: {
+            configure(nitroConfig) {
+                if (!resolved.enabled)
+                    return nitroConfig;
+                let generated = false;
+                const hooks = nitroConfig.hooks ?? {};
+                const previousPrerenderDone = hooks["prerender:done"];
+                const previousRollupBefore = hooks["rollup:before"];
+                const generate = async () => {
+                    if (generated)
+                        return;
+                    const built = await writePwaBuildArtifacts({
+                        outputDir: nitroConfig.output?.dir ?? configuredOutputDir,
+                        publicDir: nitroConfig.output?.publicDir,
+                        preset: nitroConfig.preset ?? "node-server",
+                        basePath: configuredBasePath,
+                        options: resolved,
+                    });
+                    generated = true;
+                    console.info(`[farm:pwa] Generated ${built.workerUrl} with ${built.precacheUrls.length} precached files`);
+                };
+                return {
+                    ...nitroConfig,
+                    hooks: {
+                        ...hooks,
+                        "prerender:done": async (...args) => {
+                            await callConfiguredHooks(previousPrerenderDone, args);
+                            await generate();
+                        },
+                        "rollup:before": async (...args) => {
+                            await callConfiguredHooks(previousRollupBefore, args);
+                            if (isNitroPrerenderBuild(args[0]))
+                                return;
+                            await generate();
+                        },
+                    },
+                };
+            },
+        },
+        client: {
+            public: publicConfig,
+            async setup({ public: config, isProd }) {
+                if (!config.enabled || !isProd || !("serviceWorker" in navigator))
+                    return undefined;
+                const registration = await navigator.serviceWorker.register(config.workerUrl, {
+                    scope: config.scope,
+                });
+                const hadControllerAtSetup = Boolean(navigator.serviceWorker.controller);
+                let applyingUpdate = false;
+                let reloading = false;
+                const applyUpdate = () => {
+                    applyingUpdate = true;
+                    registration.waiting?.postMessage({ type: "FARM_PWA_SKIP_WAITING" });
+                };
+                const announceUpdate = () => {
+                    if (config.update === "auto") {
+                        applyUpdate();
+                        return;
+                    }
+                    window.dispatchEvent(new CustomEvent("farm:pwa:update-available", {
+                        detail: { registration, applyUpdate },
+                    }));
+                };
+                const handleUpdateFound = () => {
+                    const installing = registration.installing;
+                    if (!installing)
+                        return;
+                    const handleStateChange = () => {
+                        if (installing.state === "installed" && navigator.serviceWorker.controller) {
+                            announceUpdate();
+                        }
+                    };
+                    installing.addEventListener("statechange", handleStateChange);
+                };
+                const handleControllerChange = () => {
+                    window.dispatchEvent(new CustomEvent("farm:pwa:updated"));
+                    if (((config.update === "auto" && hadControllerAtSetup) || applyingUpdate) &&
+                        !reloading) {
+                        reloading = true;
+                        window.location.reload();
+                    }
+                };
+                registration.addEventListener("updatefound", handleUpdateFound);
+                navigator.serviceWorker.addEventListener("controllerchange", handleControllerChange);
+                window.__FARM_PWA__ = { registration, applyUpdate };
+                if (registration.waiting && navigator.serviceWorker.controller)
+                    announceUpdate();
+                return {
+                    cleanup() {
+                        registration.removeEventListener("updatefound", handleUpdateFound);
+                        navigator.serviceWorker.removeEventListener("controllerchange", handleControllerChange);
+                        if (window.__FARM_PWA__?.registration === registration)
+                            delete window.__FARM_PWA__;
+                    },
+                };
+            },
+            close({ state }) {
+                state?.cleanup?.();
+            },
+        },
+    });
+}
+function isNitroPrerenderBuild(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const options = value.options;
+    return options?.preset === "nitro-prerender";
+}
+async function callConfiguredHooks(value, args) {
+    const hooks = Array.isArray(value) ? value : [value];
+    for (const hook of hooks) {
+        if (typeof hook === "function")
+            await hook(...args);
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@farm.js/pwa",
+  "version": "0.1.0-beta.0",
+  "description": "Installable, offline-aware Progressive Web Apps for Farm.js",
+  "keywords": [
+    "farm.js",
+    "offline",
+    "progressive-web-app",
+    "pwa",
+    "service-worker"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-pwa"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@farm.js/core": "0.1.0-beta.68"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}