@unplugin-pwa/core 0.0.0 → 0.0.1

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/info.d.ts

@@ -0,0 +1,71 @@
+declare module 'virtual:pwa-info' {
+  export interface PwaInfo {
+    pwaInDevEnvironment: boolean
+    /**
+     * The web manifest will be always here.
+     */
+    webManifest: {
+      href: string
+      useCredentials: boolean
+      /**
+       * The link tag with or without `crossorigin`:
+       * - `<link rel="manifest" href="<webManifestUrl>" />`.
+       * - `<link rel="manifest" href="<webManifestUrl>" crossorigin="use-credentials" />`.
+       */
+      linkTag: string
+    }
+    /**
+     * The service worker data will be exposed only if required, that's, will **NOT** be exposed if:
+     * - not using `pwaPluginOptions.injectRegister` with `script`, `script-defer` or `inline` values
+     * - if using `pwaPluginOptions.injectRegister` with `auto` (default) and importing any of the virtual modules
+     *
+     * **NOTE**: `registerSW` will be `undefined` if:
+     * - SSR build (only if required)
+     * - PWA is disabled: `pwaPluginOptions.disable = true`
+     * - running `Dev Server` and `pwaPluginOptions.devOptions.enabled = false` (default).
+     */
+    registerSW?: {
+      /**
+       * Should use `type="module"?
+       *
+       * **NOTE**: `module` will be `true` **ONLY** at `Dev server` and using dual service worker workers: `classic-and-module`.
+       */
+      module: boolean
+      /**
+       * When this flag is `inline` the service worker must be registered via inline script otherwise registered via script with src attribute `registerSW.js`.
+       */
+      mode: 'inline' | 'script' | 'script-defer'
+      /**
+       * The path for the inline script: will contain the service worker url.
+       */
+      inlinePath: string
+      /**
+       * The path for the src script for `registerSW.js`.
+       */
+      registerPath: string
+      /**
+       * The scope for the service worker: only required for `inline: true`.
+       */
+      scope: string
+      /**
+       * The type for the service worker: only required for `inline: true`.
+       */
+      type: 'classic' | 'module'
+      /**
+       * The script tag if `shouldRegisterSW` returns `true`.
+       */
+      scriptTag?: string
+    }
+  }
+  /**
+   * Return the PWA information if available.
+   *
+   * This property will be `undefined` if:
+   * - SSR build
+   * - PWA is disabled: `pwaPluginOptions.disable = true`
+   * - running `Dev Server` and `pwaPluginOptions.devOptions.enabled = false` (default).
+   *
+   * @returns The PWA information.
+   */
+  export const pwaInfo: PwaInfo | undefined
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@unplugin-pwa/core",
-  "version": "0.0.0",
-  "main": "index.js",
+  "type": "module",
+  "version": "0.0.1",
   "description": "PWA bundler-agnostic core logic and utilities",
-  "publishConfig": {
-    "access": "public"
-  },
   "author": "Vite PWA's Team",
+  "maintainers": [
+    "userquin <userquin@gmail.com>"
+  ],
   "license": "MIT",
+  "funding": "https://github.com/sponsors/antfu",
   "homepage": "https://github.com/vite-pwa/unplugin-pwa#readme",
   "repository": {
     "type": "git",
@@ -25,5 +26,130 @@
     "agnostic",
     "configuration",
     "helpers"
-  ]
-}
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts"
+    },
+    "./additional-manifest-entries": "./dist/additional-manifest-entries.mjs",
+    "./build-pwa-asset": "./dist/build-pwa-asset.mjs",
+    "./config": "./dist/config.mjs",
+    "./constants": "./dist/constants.mjs",
+    "./context": "./dist/context.mjs",
+    "./context-types": {
+      "types": "./dist/context-types.d.mts"
+    },
+    "./create-generate-register-sw-script": "./dist/create-generate-register-sw-script.mjs",
+    "./create-web-manifest-html-link": "./dist/create-web-manifest-html-link.mjs",
+    "./dual-sw-utilities": "./dist/dual-sw-utilities.mjs",
+    "./generate-register-sw": "./dist/generate-register-sw.mjs",
+    "./generate-web-manifest": "./dist/generate-web-manifest.mjs",
+    "./html": "./dist/html.mjs",
+    "./helpers": "./dist/helpers.mjs",
+    "./inject-generate-register-sw": "./dist/inject-generate-register-sw.mjs",
+    "./inject-web-manifest-html-link": "./dist/inject-web-manifest-html-link.mjs",
+    "./inspector-utils": "./dist/inspector-utils.mjs",
+    "./logs": "./dist/logs.mjs",
+    "./prepare-pwa-context": "./dist/prepare-pwa-context.mjs",
+    "./prepare-sw-names": "./dist/prepare-sw-names.mjs",
+    "./resolve-inspector-dist": "./dist/resolve-inspector-dist.mjs",
+    "./dev/prepare-sw-names-and-glob-directory": "./dist/dev/prepare-sw-names-and-glob-directory.mjs",
+    "./dev/prepare-temp-folder": "./dist/dev/prepare-temp-folder.mjs",
+    "./pwa-assets/build": "./dist/pwa-assets/build.mjs",
+    "./pwa-assets/config": "./dist/pwa-assets/config.mjs",
+    "./pwa-assets/dev": "./dist/pwa-assets/dev.mjs",
+    "./pwa-assets/generator": "./dist/pwa-assets/generator.mjs",
+    "./pwa-assets/html": "./dist/pwa-assets/html.mjs",
+    "./pwa-assets/manifest": "./dist/pwa-assets/manifest.mjs",
+    "./pwa-assets/options": "./dist/pwa-assets/options.mjs",
+    "./pwa-assets/types": {
+      "types": "./dist/pwa-assets/types.d.mts"
+    },
+    "./pwa-assets/utils": "./dist/pwa-assets/utils.mjs",
+    "./types": {
+      "types": "./types/index.d.ts"
+    },
+    "./preact": {
+      "types": "./preact.d.ts"
+    },
+    "./react": {
+      "types": "./react.d.ts"
+    },
+    "./react-legacy": {
+      "types": "./react-legacy.d.ts"
+    },
+    "./solid": {
+      "types": "./solid.d.ts"
+    },
+    "./svelte": {
+      "types": "./svelte.d.ts"
+    },
+    "./vanillajs": {
+      "types": "./vanillajs.d.ts"
+    },
+    "./vue": {
+      "types": "./vue.d.ts"
+    },
+    "./client": {
+      "types": "./client.d.ts"
+    },
+    "./info": {
+      "types": "./info.d.ts"
+    },
+    "./pwa-assets": {
+      "types": "./pwa-assets.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.d.ts",
+    "dist",
+    "types"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "peerDependencies": {
+    "@vite-pwa/assets-generator": "^1.0.0 || ^2.0.0",
+    "rolldown": "^1.0.0-0",
+    "vite": "^3.1.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@vite-pwa/assets-generator": {
+      "optional": true
+    },
+    "rolldown": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@vite-pwa/workbox-build": "^8.0.13",
+    "hookable": "^6.1.2"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@vite-pwa/assets-generator": "^2.0.0",
+    "preact": "^10.29.8",
+    "react": "^19.3.1",
+    "rolldown": "^1.2.14",
+    "solid-js": "^1.9.17",
+    "svelte": "^5.57.2",
+    "vite": "^8.3.5",
+    "vue": "^3.5.44"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "test:typecheck": "tsc --noEmit",
+    "test:ci": "vitest run --coverage",
+    "test": "vitest",
+    "test:ui": "vitest --ui --open --coverage"
+  }
+}

package/preact.d.ts

@@ -0,0 +1,17 @@
+declare module 'virtual:pwa-register/preact' {
+  import type { PWATrustedScriptURL, RegisterSWOptions } from '@unplugin-pwa/core/types'
+  // eslint-disable-next-line ts/ban-ts-comment
+  // @ts-ignore ignore when preact/hooks is not installed
+  import type { Dispatch, StateUpdater } from 'preact/hooks'
+
+  export type { PWATrustedScriptURL, RegisterSWOptions }
+
+  export function useRegisterSW(options?: RegisterSWOptions): {
+    needRefresh: [boolean, Dispatch<StateUpdater<boolean>>]
+    offlineReady: [boolean, Dispatch<StateUpdater<boolean>>]
+    /**
+     * Reloads the current window to allow the service worker take the control.
+     */
+    updateServiceWorker: () => Promise<void>
+  }
+}

package/pwa-assets.d.ts

@@ -0,0 +1,40 @@
+/* WARNING: these virtual modules are meant to be used by integrations and not being consumed directly from applications */
+
+declare module 'virtual:pwa-assets/head' {
+  export interface PWAAssetHeadLink {
+    id?: string
+    rel: 'apple-touch-startup-image' | 'apple-touch-icon' | 'icon'
+    href: string
+    media?: string
+    sizes?: string
+    type?: string
+  }
+
+  export interface ColorSchemeMeta {
+    name: string
+    content: string
+  }
+
+  export interface PWAAssetsHead {
+    links: PWAAssetHeadLink[]
+    themeColor?: ColorSchemeMeta
+  }
+
+  export const pwaAssetsHead: PWAAssetsHead
+}
+
+declare module 'virtual:pwa-assets/icons' {
+  import type { AppleSplashScreenLink, FaviconLink, HtmlLink, IconAsset } from '@vite-pwa/assets-generator/api'
+
+  export type PWAAssetIcon<T extends HtmlLink> = Omit<IconAsset<T>, 'buffer'>
+
+  export interface PWAAssetsIcons {
+    favicon: Record<string, PWAAssetIcon<FaviconLink>>
+    transparent: Record<string, PWAAssetIcon<HtmlLink>>
+    maskable: Record<string, PWAAssetIcon<HtmlLink>>
+    apple: Record<string, PWAAssetIcon<HtmlLink>>
+    appleSplashScreen: Record<string, PWAAssetIcon<AppleSplashScreenLink>>
+  }
+
+  export const pwaAssetsIcons: PWAAssetsIcons
+}

package/react-legacy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This module is a legacy version of the PWA register hook for React and will
+ * be removed in the next major version.
+ * @deprecated use `virtual:pwa-register/react` instead
+ */
+declare module 'virtual:pwa-register/react-legacy' {
+  import type { PWATrustedScriptURL, RegisterSWOptions } from '@unplugin-pwa/core/types'
+  // eslint-disable-next-line ts/ban-ts-comment
+  // @ts-ignore ignore when react is not installed
+  import type { Dispatch, SetStateAction } from 'react'
+
+  export type { PWATrustedScriptURL, RegisterSWOptions }
+
+  export function useRegisterSW(options?: RegisterSWOptions): {
+    needRefresh: [boolean, Dispatch<SetStateAction<boolean>>]
+    offlineReady: [boolean, Dispatch<SetStateAction<boolean>>]
+    /**
+     * Reloads the current window to allow the service worker take the control.
+     */
+    updateServiceWorker: () => Promise<void>
+  }
+}

package/react.d.ts

@@ -0,0 +1,17 @@
+declare module 'virtual:pwa-register/react' {
+  import type { PWATrustedScriptURL, RegisterSWOptions } from '@unplugin-pwa/core/types'
+  // eslint-disable-next-line ts/ban-ts-comment
+  // @ts-ignore ignore when react is not installed
+  import type { Dispatch, SetStateAction } from 'react'
+
+  export type { PWATrustedScriptURL, RegisterSWOptions }
+
+  export function useRegisterSW(options?: RegisterSWOptions): {
+    needRefresh: [boolean, Dispatch<SetStateAction<boolean>>]
+    offlineReady: [boolean, Dispatch<SetStateAction<boolean>>]
+    /**
+     * Reloads the current window to allow the service worker take the control.
+     */
+    updateServiceWorker: () => Promise<void>
+  }
+}

package/solid.d.ts

@@ -0,0 +1,17 @@
+declare module 'virtual:pwa-register/solid' {
+  import type { PWATrustedScriptURL, RegisterSWOptions } from '@unplugin-pwa/core/types'
+  // eslint-disable-next-line ts/ban-ts-comment
+  // @ts-ignore ignore when solid-js is not installed
+  import type { Accessor, Setter } from 'solid-js'
+
+  export type { PWATrustedScriptURL, RegisterSWOptions }
+
+  export function useRegisterSW(options?: RegisterSWOptions): {
+    needRefresh: [Accessor<boolean>, Setter<boolean>]
+    offlineReady: [Accessor<boolean>, Setter<boolean>]
+    /**
+     * Reloads the current window to allow the service worker take the control.
+     */
+    updateServiceWorker: () => Promise<void>
+  }
+}

package/svelte.d.ts

@@ -0,0 +1,17 @@
+declare module 'virtual:pwa-register/svelte' {
+  import type { PWATrustedScriptURL, RegisterSWOptions } from '@unplugin-pwa/core/types'
+  // eslint-disable-next-line ts/ban-ts-comment
+  // @ts-ignore ignore when svelte is not installed
+  import type { Writable } from 'svelte/store'
+
+  export type { PWATrustedScriptURL, RegisterSWOptions }
+
+  export function useRegisterSW(options?: RegisterSWOptions): {
+    needRefresh: Writable<boolean>
+    offlineReady: Writable<boolean>
+    /**
+     * Reloads the current window to allow the service worker take the control.
+     */
+    updateServiceWorker: () => Promise<void>
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,43 @@
+import type { TrustedScriptURL } from 'trusted-types/lib'
+
+export type { TrustedScriptURL } from 'trusted-types/lib'
+
+/**
+ * A function that returns the service worker trusted script url.
+ *
+ * @param classic Whether the browser is in legacy mode (i.e. not supporting ES modules in service workers).
+ * @param swUrl The url for the service worker.
+ * @returns The service worker script url.
+ */
+export type PWATrustedScriptURL = (classic: boolean, swUrl: string) => TrustedScriptURL
+
+export interface RegisterSWOptions {
+  immediate?: boolean
+  /**
+   * Called when the service worker has taken control and the page would normally reload.
+   *
+   * Useful to fully control the reload flow (for example, to defer reload until the next
+   * SPA navigation).
+   */
+  onNeedReload?: () => void
+  onNeedRefresh?: () => void
+  onOfflineReady?: () => void
+  /**
+   * Service worker trusted script url.
+   *
+   * @since 2.0.0
+   */
+  trustedScriptUrl?: TrustedScriptURL | PWATrustedScriptURL
+  /**
+   * Called once the service worker is registered (requires version `0.12.8+`).
+   *
+   * @param swScriptUrl The service worker script url.
+   * @param registration The service worker registration if available.
+   */
+  onRegisteredSW?: (swScriptUrl: string, registration: ServiceWorkerRegistration | undefined) => void
+  onRegisterError?: (error: unknown) => void
+  /**
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/updateViaCache
+   */
+  updateViaCache?: ServiceWorkerUpdateViaCache
+}

package/types/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/vanillajs.d.ts

@@ -0,0 +1,13 @@
+declare module 'virtual:pwa-register' {
+  import type { PWATrustedScriptURL, RegisterSWOptions } from '@unplugin-pwa/core/types'
+
+  export type { PWATrustedScriptURL, RegisterSWOptions }
+
+  /**
+   * Registers the service worker returning a callback to reload the current page when an update is found.
+   *
+   * @param options the options to register the service worker.
+   * @return The callback to activate the new service worker.
+   */
+  export function registerSW(options?: RegisterSWOptions): () => Promise<void>
+}

package/vue.d.ts

@@ -0,0 +1,17 @@
+declare module 'virtual:pwa-register/vue' {
+  import type { PWATrustedScriptURL, RegisterSWOptions, TrustedScriptURL } from '@unplugin-pwa/core/types'
+  // eslint-disable-next-line ts/ban-ts-comment
+  // @ts-ignore ignore when vue is not installed
+  import type { Ref } from 'vue'
+
+  export type { PWATrustedScriptURL, RegisterSWOptions, TrustedScriptURL }
+
+  export function useRegisterSW(options?: RegisterSWOptions): {
+    needRefresh: Ref<boolean>
+    offlineReady: Ref<boolean>
+    /**
+     * Reloads the current window to allow the service worker take the control.
+     */
+    updateServiceWorker: () => Promise<void>
+  }
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};