@unplugin-pwa/core 0.0.0 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-PRESENT Anthony Fu <https://github.com/antfu>
+
+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

@@ -1,3 +1,104 @@
-# @unplugin-pwa/core
+<p align='center'>
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vite-pwa/.github/main/unplugin-pwa-core-hero-dark.svg" />
+        <img src="https://raw.githubusercontent.com/vite-pwa/.github/main/unplugin-pwa-core-hero.svg" alt="Bundler-agnostic core logic and utilities for PWA logo">
+    </picture>
+</p>
 
-This is a stub package published by setup-trusted-publishing to enable OIDC trusted publishing configuration.
+<h1 align="center">Bundler-agnostic core logic and utilities for PWA</h1>
+
+<p align='center'>
+<a href='https://npmx.dev/package/@unplugin-pwa/core' target="_blank" rel="noopener noreferrer">
+<img src='https://img.shields.io/npm/v/@unplugin-pwa/core?color=33A6B8&label=' alt="NPM version">
+</a>
+<a href="https://npmx.dev/package/@unplugin-pwa/core" target="_blank" rel="noopener noreferrer">
+    <img alt="NPM Downloads" src="https://img.shields.io/npm/dm/@unplugin-pwa/core?color=476582&label=">
+</a>
+<a href="https://unplugin-pwa.netlify.app/unplugin-pwa/core.html" target="_blank" rel="noopener noreferrer">
+    <img src="https://img.shields.io/static/v1?label=&message=docs%20%26%20guides&color=2e859c" alt="Docs & Guides">
+</a>
+<br>
+<a href="https://github.com/vite-pwa/unplugin-pwa" target="_blank" rel="noopener noreferrer">
+<img alt="GitHub stars" src="https://img.shields.io/github/stars/vite-pwa/unplugin-pwa?style=social">
+</a>
+</p>
+
+<br>
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
+    <img src="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg" alt="Anthony Fu SVG sponsors image" />
+  </a>
+</p>
+
+## 🧱 What is `@unplugin-pwa/core`?
+
+The bundler-agnostic foundation of `unplugin-pwa`. It contains the shared PWA logic (configuration resolution, Web App Manifest, service worker registration, virtual modules, PWA assets and inspector utilities) with no dependency on any specific bundler.
+
+> 💡 **Note:** this package is aimed at integration authors. If you just want to add PWA support to your app, use an integration such as [`@unplugin-pwa/vite`](https://npmx.dev/package/@unplugin-pwa/vite) instead.
+
+## 🧩 What's inside?
+
+Each area is exposed as its own subpath export, so you only import what you need and everything stays tree-shakable.
+
+| Area | Subpaths |
+| --- | --- |
+| Configuration and context | `config`, `context`, `context-types`, `constants`, `prepare-pwa-context`, `prepare-sw-names` |
+| Web App Manifest | `generate-web-manifest`, `create-web-manifest-html-link`, `inject-web-manifest-html-link` |
+| Service worker registration | `generate-register-sw`, `create-generate-register-sw-script`, `inject-generate-register-sw`, `generate-virtual-module` |
+| Service worker utilities | `additional-manifest-entries`, `dual-sw-utilities`, `build-pwa-asset` |
+| Development | `dev/prepare-sw-names-and-glob-directory`, `dev/prepare-temp-folder` |
+| PWA Assets | `pwa-assets/*` (`build`, `config`, `dev`, `generator`, `html`, `manifest`, `options`, `types`, `utils`) |
+| Inspector | `inspector-utils`, `resolve-inspector-dist` |
+| Misc | `html`, `helpers`, `logs` |
+
+## 🏷️ Client types
+
+The virtual module and framework type declarations also live here, shared by all integrations:
+
+| Subpath | Use it for |
+| --- | --- |
+| `@unplugin-pwa/core/client` | Virtual modules (base) |
+| `@unplugin-pwa/core/vanillajs` | Vanilla JavaScript |
+| `@unplugin-pwa/core/vue` | Vue 3 |
+| `@unplugin-pwa/core/react` | React |
+| `@unplugin-pwa/core/react-legacy` | React (legacy) |
+| `@unplugin-pwa/core/preact` | Preact |
+| `@unplugin-pwa/core/solid` | SolidJS |
+| `@unplugin-pwa/core/svelte` | Svelte |
+| `@unplugin-pwa/core/info` | `virtual:pwa-info` |
+| `@unplugin-pwa/core/pwa-assets` | PWA Assets virtual modules |
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@unplugin-pwa/core/vue"]
+  }
+}
+```
+
+## 📋 Requirements
+
+`@unplugin-pwa/core` requires **Node 22.14.0 or above**.
+
+The following peer dependencies are all optional; install them only if your integration needs them:
+
+- `vite`: from 3.1 to 8.
+- `rolldown`: 1.0.0 or above.
+- `@vite-pwa/assets-generator`: 1.x or 2.x, only when using PWA Assets.
+
+## 📦 Install
+
+```bash
+npm i -D @unplugin-pwa/core
+
+# yarn
+yarn add -D @unplugin-pwa/core
+
+# pnpm
+pnpm add -D @unplugin-pwa/core
+```
+
+## 📄 License
+
+[MIT](./LICENSE) License &copy; 2026-PRESENT [Anthony Fu](https://github.com/antfu)

package/client.d.ts

@@ -0,0 +1,6 @@
+import './vue.d.ts'
+import './preact.d.ts'
+import './react.d.ts'
+import './svelte.d.ts'
+import './solid.d.ts'
+import './vanillajs.d.ts'

package/dist/additional-manifest-entries.d.mts

@@ -0,0 +1,10 @@
+/*!
+  MIT License
+  
+  Copyright (c) 2020-PRESENT Anthony Fu <https://github.com/antfu>
+
+  https://github.com/userquin/quini-pwa-monorepo/blob/main/LICENSE.
+*/
+import { PWAPluginContext } from "./context-types.mjs";
+import { ManifestEntry } from "@vite-pwa/workbox-build/types";
+export declare function additionalManifestEntriesFactory(ctx: PWAPluginContext<any, any, any>, mapFile: (url: string) => string): () => AsyncGenerator<string | ManifestEntry, undefined, void>;

package/dist/additional-manifest-entries.mjs

@@ -0,0 +1,60 @@
+/*!
+  MIT License
+  
+  Copyright (c) 2020-PRESENT Anthony Fu <https://github.com/antfu>
+
+  https://github.com/userquin/quini-pwa-monorepo/blob/main/LICENSE.
+*/
+import { generateWebManifest } from "./generate-web-manifest.mjs";
+// src/additional-manifest-entries.ts
+function additionalManifestEntriesFactory(ctx, mapFile) {
+	return async function* additionalManifestEntries() {
+		const { includeManifest, includeManifestIcons, includeAssets, includeManifestShortcutIcons, includeManifestScreenshots } = ctx.resolvedOptions;
+		if (includeManifest || includeManifestIcons || includeAssets || includeManifestScreenshots || includeManifestShortcutIcons) {
+			const manifest = ctx.resolvedOptions.manifest;
+			const [{ hash }, { readFile }] = await Promise.all([import("node:crypto"), import("node:fs/promises")]);
+			if (manifest) {
+				if (includeManifest) yield {
+					url: ctx.resolvedOptions.manifestFilename,
+					revision: hash("md5", generateWebManifest(ctx), "hex")
+				};
+				if (includeManifestIcons && manifest.icons) {
+					const consumerIcons = /* @__PURE__ */ new Set();
+					if (ctx.consumerOptions.manifest && ctx.consumerOptions.manifest.icons) {
+						for (const icon of ctx.consumerOptions.manifest.icons) if (icon.src) consumerIcons.add(mapFile(icon.src));
+					}
+					for (const icon of manifest.icons) if (icon.src) {
+						const path = mapFile(icon.src);
+						if (!consumerIcons.has(path)) continue;
+						yield {
+							url: icon.src,
+							revision: hash("md5", await readFile(path, "utf-8"), "hex")
+						};
+					}
+				}
+				if (includeManifestShortcutIcons && manifest.shortcuts) {
+					for (const shortcut of manifest.shortcuts) if (shortcut.icons) {
+						for (const icons of shortcut.icons) if (icons.src) yield {
+							url: icons.src,
+							revision: hash("md5", await readFile(mapFile(icons.src), "utf-8"), "hex")
+						};
+					}
+				}
+				if (includeManifestScreenshots && manifest.screenshots) for (const screenshot of manifest.screenshots) yield {
+					url: screenshot.src,
+					revision: hash("md5", await readFile(mapFile(screenshot.src), "utf-8"), "hex")
+				};
+				if (includeAssets) {
+					const assets = typeof includeAssets === "string" ? [includeAssets] : includeAssets;
+					for (const asset of assets) yield {
+						url: asset,
+						revision: hash("md5", await readFile(mapFile(asset), "utf-8"), "hex")
+					};
+				}
+			}
+		}
+		const consumerGenerator = ctx.consumerOptions.additionalManifestEntriesGenerator;
+		if (consumerGenerator) yield* consumerGenerator();
+	};
+}
+export { additionalManifestEntriesFactory };

package/dist/build-pwa-asset.d.mts

@@ -0,0 +1,18 @@
+/*!
+  MIT License
+  
+  Copyright (c) 2020-PRESENT Anthony Fu <https://github.com/antfu>
+
+  https://github.com/userquin/quini-pwa-monorepo/blob/main/LICENSE.
+*/
+import { w as VitePWAStrategy } from "./types-BhwjnGLn.mjs";
+import { Bundler, PWAPluginContext } from "./context-types.mjs";
+import { SWType } from "@vite-pwa/workbox-build/types";
+export type DependenciesResolved = NonNullable<Pick<import('rolldown').Plugin, 'resolveId' | 'load'>>;
+/**
+ * This module will build `registerSW` or any virtual module.
+ * @param code The code to build.
+ * @param ctx The context of the PWA bundler.
+ * @param resolver Rolldown hooks to resolve dependencies.
+ */
+export declare function buildPwaAsset<B extends Bundler, UserStrategy extends VitePWAStrategy, T extends SWType>(code: string, ctx: PWAPluginContext<B, UserStrategy, T>, resolver?: DependenciesResolved): Promise<string>;

package/dist/build-pwa-asset.mjs

@@ -0,0 +1,87 @@
+/*!
+  MIT License
+  
+  Copyright (c) 2020-PRESENT Anthony Fu <https://github.com/antfu>
+
+  https://github.com/userquin/quini-pwa-monorepo/blob/main/LICENSE.
+*/
+import { resolveSWNames } from "@vite-pwa/workbox-build/utils/resolve-sw-names";
+// src/build-pwa-asset.ts
+/**
+* This module will build `registerSW` or any virtual module.
+* @param code The code to build.
+* @param ctx The context of the PWA bundler.
+* @param resolver Rolldown hooks to resolve dependencies.
+*/
+async function buildPwaAsset(code, ctx, resolver) {
+	const { filename = "sw.js" } = ctx.consumerOptions;
+	const { strategy, scope, buildBase, base: useBase, buildSW, injectManifest, updateViaCache } = ctx.resolvedOptions;
+	const useGenerateSW = strategy === "generate-sw";
+	const { swDestPath, classicSWDestPath, moduleSWDestPath } = resolveSWNames(filename, strategy === "generate-sw" ? "" : strategy === "build-sw" ? buildSW.swSrc : injectManifest.swSrc, useGenerateSW);
+	let swType = "classic";
+	if (ctx.devEnvironment) {
+		if (ctx.resolvedOptions.devOptions?.type === "module") swType = "module";
+	} else if (ctx.resolvedOptions.swType === "module") swType = "module";
+	const devEnabled = ctx.resolvedOptions.devOptions?.enabled === true;
+	const base = ctx.devEnvironment ? useBase : buildBase;
+	return await buildPwaAssetWithRolldown(code, {
+		"import.meta.PWA_ESM_FALLBACK_SW": JSON.stringify(ctx.resolvedOptions.swType === "classic-and-module"),
+		"import.meta.PWA_SELF_DESTROYING_SW": JSON.stringify(ctx.strategy === "self-destroy-sw"),
+		"import.meta.PWA_SW_URL": JSON.stringify(`${base}${swDestPath}`),
+		"import.meta.PWA_SW_CLASSIC_URL": JSON.stringify(`${base}${classicSWDestPath}`),
+		"import.meta.PWA_SW_MODULE_URL": JSON.stringify(`${base}${moduleSWDestPath}`),
+		"import.meta.PWA_SW_SCOPE": JSON.stringify(scope),
+		"import.meta.PWA_SW_TYPE": JSON.stringify(swType),
+		"import.meta.PWA_SW_UPDATE_VIA_CACHE": JSON.stringify(updateViaCache),
+		"import.meta.PWA_DEV_SERVER": JSON.stringify(ctx.devEnvironment),
+		"import.meta.PWA_SW_AUTO_UPDATE": JSON.stringify(ctx.resolvedOptions.registerType === "autoUpdate"),
+		"import.meta.PWA_DEV_ENABLED": JSON.stringify(devEnabled),
+		"import.meta.PWA_DEV_UI_ENABLED": JSON.stringify(devEnabled && ctx.resolvedOptions.devOptions?.enableUISwitcher === true),
+		"import.meta.PWA_DEV_CURRENT_SW_TYPE": JSON.stringify(ctx.dev.options.swType)
+	}, ctx.devEnvironment, ctx.resolvedOptions.minify, resolver);
+}
+async function writeAsset(instance, options) {
+	try {
+		return await instance.generate(options);
+	} finally {
+		await instance.close();
+	}
+}
+async function buildPwaAssetWithRolldown(code, define, isDev, minify, resolver) {
+	const { rolldown } = await import("rolldown");
+	const input = "asset.js";
+	const plugins = [{
+		name: "pwa-asset-resolver",
+		resolveId(id) {
+			return id === input ? input : void 0;
+		},
+		load(id) {
+			return id === input ? code : void 0;
+		}
+	}];
+	if (resolver) plugins.push({
+		name: "pwa-asset-custom-resolver",
+		resolveId: resolver.resolveId,
+		load: resolver.load
+	});
+	return (await writeAsset(await rolldown({
+		input,
+		platform: "browser",
+		treeshake: true,
+		logLevel: "warn",
+		plugins,
+		transform: { define }
+	}), {
+		format: "esm",
+		topLevelVar: true,
+		cleanDir: false,
+		comments: {
+			legal: !isDev && !minify,
+			jsdoc: false,
+			annotation: false
+		},
+		minify: isDev ? false : minify,
+		codeSplitting: false
+	})).output.find((e) => e.fileName === input && e.type === "chunk").code;
+}
+export { buildPwaAsset };

package/dist/config.d.mts

@@ -0,0 +1,75 @@
+/*!
+  MIT License
+  
+  Copyright (c) 2020-PRESENT Anthony Fu <https://github.com/antfu>
+
+  https://github.com/userquin/quini-pwa-monorepo/blob/main/LICENSE.
+*/
+import { C as VitePWAOptions, w as VitePWAStrategy, y as ResolvedVitePWAOptions } from "./types-BhwjnGLn.mjs";
+import { ExtractStrategy } from "./context-types.mjs";
+import { SWType } from "@vite-pwa/workbox-build/types";
+export declare const DEFAULT_CONFIG_FILES: readonly ["pwa.config.js", "pwa.config.ts", "pwa.config.mjs", "pwa.config.mts"];
+export type LoaderType<S extends VitePWAStrategy, T extends SWType> = VitePWAOptions<S, T> | (() => VitePWAOptions<S, T>) | (() => Promise<VitePWAOptions<S, T>>);
+/**
+ * Loads the PWA configuration from a specified path.
+ *
+ * If the `path` options is not provided, it will return the provided options as is.
+ *
+ * Otherwise, it will attempt to load the configuration from the specified path
+ * and merge it with the provided options if `mergeOptions` is set to true.
+ *
+ * @param options The partial PWA options to load.
+ * @returns The resolved PWA options, merged with the provided options if `mergeOptions` is set to true.
+ */
+export declare function loadConfiguration<S extends VitePWAStrategy, T extends SWType>(options: Partial<VitePWAOptions<S, T>>): Promise<Partial<VitePWAOptions<S, T>>>;
+/**
+ * Loads the first existing default configuration file from the current working directory.
+ *
+ * The default configuration files are searched in the following order:
+ * - `pwa.config.js`
+ * - `pwa.config.ts`
+ * - `pwa.config.mjs`
+ * - `pwa.config.mts`
+ *
+ * @param cwd The current working directory to search for the default configuration files. Defaults to `process.cwd()`.
+ * @returns The path to the first existing default configuration file, or `undefined` if none are found.
+ */
+export declare function resolveDefaultConfig(cwd?: string): string | undefined;
+/**
+ * Loads the default manifest using the `package.json` file.
+ *
+ * @param options The resolved PWA options.
+ */
+export declare function prepareManifest(options: ResolvedVitePWAOptions<any, any>): void;
+/**
+ * The resolver options containing environment information and callbacks for `resolvePwaConfiguration`.
+ */
+export interface ResolverOptions {
+  /**
+   * Whether the current environment is a development environment.
+   */
+  isDev: boolean;
+  /**
+   * When using `inject-manifest`, this callback must resolve if the strategy is wrong, the implementation should be:
+   * - if the service worker with `.ts` or `.mts` extension, then, it is `build-sw` and not `inject-manifest` strategy: must return true
+   * - if the service worker outside public dir, then, it is `build-sw` and not `inject-manifest` strategy: must return true
+   * - otherwise must return false
+   */
+  isWrongInjectManifest: (swSrc: string) => boolean | Promise<boolean>;
+}
+/**
+ * Resolves the PWA configuration based on the provided options and resolver options.
+ *
+ * This function will search for the PWA configuration file if the `path` option is not provided,
+ * and will merge the loaded configuration with the provided options.
+ *
+ * When using `inject-manifest`, the `resolverOptions.isWrongInjectManifest` callback must resolve if the strategy is wrong, the implementation should be:
+ * - if the service worker with `.ts` or `.mts` extension, then, it is `build-sw` and not `inject-manifest` strategy: must return true
+ * - if the service worker outside public dir, then, it is `build-sw` and not `inject-manifest` strategy: must return true
+ * - otherwise must return false
+ *
+ * @param pwaOptions The PWA options to resolve.
+ * @param resolverOptions The resolver options containing environment information and callbacks.
+ * @returns The resolved PWA options.
+ */
+export declare function resolvePwaConfiguration<UserStrategy extends VitePWAStrategy, T extends SWType>(pwaOptions: Partial<VitePWAOptions<UserStrategy, T>>, resolverOptions: ResolverOptions): Promise<ResolvedVitePWAOptions<ExtractStrategy<UserStrategy>, T>>;