feat: make PWA support an optional peer dependency (#2671)

antfubot · web-flow · commit 06dbc58b8daa · 2026-07-14T12:00:55.000+09:00
diff --git a/docs/features/pwa.md b/docs/features/pwa.md
@@ -31,6 +31,23 @@ The `pwa` option can be a boolean or a string to control when the service worker
 
 Since precaching every asset is heavy, `pwa` is **off by default** and should be enabled deliberately — most useful together with [`slidev build`](/guide/hosting) for a self-hosted deck you want to work offline.
 
+## Installing the PWA Plugin
+
+PWA support is powered by [`vite-plugin-pwa`](https://vite-pwa-org.netlify.app/), which ships as an **optional peer dependency**. It is not installed by default, so decks that don't opt into `pwa` never download it.
+
+The first time you enable `pwa`, the Slidev CLI detects that the package is missing and prompts you to install it:
+
+```
+? The "pwa" option requires the "vite-plugin-pwa" package, which is not installed
+  in your project. Install it now? › (Y/n)
+```
+
+Confirm the prompt and Slidev installs it for you with your project's package manager (or globally, when Slidev itself is installed globally). In a non-interactive environment (such as CI) the prompt can't be shown, so install it ahead of time instead:
+
+```bash
+npm i -D vite-plugin-pwa
+```
+
 ## How It Works
 
 When you serve the built deck, the service worker downloads and caches all deck assets in the background. A small indicator in the bottom-right corner shows `Caching for offline…` while precaching is in progress, then briefly shows `Ready offline` once it completes. After that, disconnecting the network and reloading serves the whole deck — HTML, images, and video — from the cache.
diff --git a/package.json b/package.json
@@ -71,6 +71,7 @@
     "tsx": "catalog:dev",
     "typescript": "catalog:dev",
     "vite": "catalog:prod",
+    "vite-plugin-pwa": "catalog:prod",
     "vitest": "catalog:dev",
     "vue-tsc": "catalog:dev",
     "zx": "catalog:dev"
diff --git a/packages/client/shim.d.ts b/packages/client/shim.d.ts
@@ -1,4 +1,18 @@
-/// <reference types="vite-plugin-pwa/client" />
+// `vite-plugin-pwa` is an optional peer dependency (only needed when the `pwa`
+// option is enabled), so declare the subset of `virtual:pwa-register` we use
+// inline instead of `/// <reference types="vite-plugin-pwa/client" />`. When
+// PWA is off, the CLI serves a no-op stub for this module.
+declare module 'virtual:pwa-register' {
+  export interface RegisterSWOptions {
+    immediate?: boolean
+    onNeedRefresh?: () => void
+    onOfflineReady?: () => void
+    onRegisteredSW?: (swScriptUrl: string, registration: ServiceWorkerRegistration | undefined) => void
+    onRegisterError?: (error: any) => void
+  }
+
+  export function registerSW(options?: RegisterSWOptions): (reloadPage?: boolean) => Promise<void>
+}
 
 declare module '*.md' {
   // with unplugin-vue-markdown, markdowns can be treat as Vue components
diff --git a/packages/slidev/node/resolver.ts b/packages/slidev/node/resolver.ts
@@ -7,7 +7,7 @@ import { parseNi, run } from '@antfu/ni'
 import { ensurePrefix, slash } from '@antfu/utils'
 import { underline, yellow } from 'ansis'
 import globalDirs from 'global-directory'
-import { resolvePath } from 'mlly'
+import { resolve as resolveModuleUrl, resolvePath } from 'mlly'
 import { dirname, join, relative, resolve, sep } from 'pathe'
 import prompts from 'prompts'
 import { resolveGlobal } from 'resolve-global'
@@ -166,6 +166,78 @@ export async function resolveImportPath(importName: string, ensure = false) {
     throw new Error(`Failed to resolve package "${importName}"`)
 }
 
+/**
+ * Import an optional dependency (typically an optional peer dependency such as
+ * `vite-plugin-pwa`) that the user may or may not have installed. Resolution is
+ * attempted, in order, from the user's project root, the workspace root, the
+ * global registry (when Slidev runs globally), and finally the cli's own
+ * dependencies. Returns `undefined` when the package can't be resolved anywhere.
+ */
+export async function importOptionalDependency<T = any>(name: string): Promise<T | undefined> {
+  const roots: string[] = []
+  try {
+    const { userRoot, userWorkspaceRoot } = await getRoots()
+    roots.push(userRoot)
+    if (userWorkspaceRoot !== userRoot)
+      roots.push(userWorkspaceRoot)
+  }
+  catch { }
+
+  for (const root of roots) {
+    try {
+      return await import(await resolveModuleUrl(name, { url: pathToFileURL(`${root}${sep}`).href }))
+    }
+    catch { }
+  }
+
+  if (isInstalledGlobally.value) {
+    try {
+      return await import(resolveGlobal(name))
+    }
+    catch { }
+  }
+
+  try {
+    return await import(name)
+  }
+  catch { }
+
+  return undefined
+}
+
+/**
+ * Prompt the user to install a missing optional dependency, then install it
+ * with the detected package manager. Exits the process when the user declines
+ * or when stdin isn't interactive (so it can't prompt).
+ *
+ * `purpose` describes why the package is needed, e.g. `The "pwa" option`.
+ */
+export async function promptForOptionalInstallation(pkgName: string, purpose: string): Promise<void> {
+  // Check if stdin is available for prompts (i.e., is a TTY)
+  if (!process.stdin.isTTY) {
+    console.error(
+      `${purpose} requires the "${pkgName}" package, which is not installed, and cannot prompt for installation. `
+      + `Install it with \`npm i -D ${pkgName}\` (or your package manager's equivalent) and try again.`,
+    )
+    process.exit(1)
+  }
+
+  const { confirm } = await prompts({
+    name: 'confirm',
+    initial: 'Y',
+    type: 'confirm',
+    message: `${purpose} requires the "${yellow(pkgName)}" package, which is not installed ${underline(isInstalledGlobally.value ? 'globally' : 'in your project')}. Install it now?`,
+  })
+
+  if (!confirm)
+    process.exit(1)
+
+  if (isInstalledGlobally.value)
+    await run(parseNi, ['-g', pkgName])
+  else
+    await run(parseNi, [pkgName])
+}
+
 /**
  * Find the root of the package. If Slidev is installed globally, it will also search globally.
  */
diff --git a/packages/slidev/node/vite/pwa.ts b/packages/slidev/node/vite/pwa.ts
@@ -1,18 +1,27 @@
 import type { ResolvedSlidevOptions } from '@slidev/types'
-import type { PluginOption } from 'vite'
-import { VitePWA } from 'vite-plugin-pwa'
+import type { Plugin, PluginOption } from 'vite'
+import { importOptionalDependency, promptForOptionalInstallation } from '../resolver'
 
-export function createPWAPlugin(options: ResolvedSlidevOptions): PluginOption {
+type VitePWAFn = (options: Record<string, any>) => PluginOption
+
+const PWA_PACKAGE = 'vite-plugin-pwa'
+
+export async function createPWAPlugin(options: ResolvedSlidevOptions): Promise<PluginOption> {
   const matchMode = (mode: string | boolean) => mode === true || mode === options.mode
   const enabled = matchMode(options.data.config.pwa)
 
+  // PWA off (the default): `vite-plugin-pwa` is an optional peer dependency, so
+  // don't require it at all. A tiny stub keeps the client's guarded
+  // `import('virtual:pwa-register')` resolvable so no PWA install is needed.
+  if (!enabled)
+    return createPWARegisterStubPlugin()
+
+  const VitePWA = await resolveVitePWA()
+
   const base = options.base ?? '/'
   const title = options.data.config.title || 'Slidev'
 
-  // Always register the plugin so `virtual:pwa-register` resolves in every build
-  // (dev included); disable service-worker generation unless `pwa` is enabled.
   return VitePWA({
-    disable: !enabled,
     registerType: 'autoUpdate',
     injectRegister: null,
     base,
@@ -34,5 +43,46 @@ export function createPWAPlugin(options: ResolvedSlidevOptions): PluginOption {
       theme_color: '#121212',
       background_color: '#121212',
     },
-  }) as PluginOption
+  })
+}
+
+/**
+ * Resolve `vite-plugin-pwa`'s `VitePWA` factory, prompting the user to install
+ * the optional peer dependency when the `pwa` option is enabled but the package
+ * is missing.
+ */
+async function resolveVitePWA(): Promise<VitePWAFn> {
+  let mod = await importOptionalDependency<{ VitePWA?: VitePWAFn, default?: { VitePWA?: VitePWAFn } }>(PWA_PACKAGE)
+
+  if (!mod?.VitePWA && !mod?.default?.VitePWA) {
+    await promptForOptionalInstallation(PWA_PACKAGE, 'The "pwa" option')
+    mod = await importOptionalDependency(PWA_PACKAGE)
+  }
+
+  const VitePWA = mod?.VitePWA ?? mod?.default?.VitePWA
+  if (!VitePWA)
+    throw new Error(`[slidev] Failed to load "${PWA_PACKAGE}", which is required by the "pwa" option.`)
+
+  return VitePWA
+}
+
+/**
+ * When PWA is disabled, resolve `virtual:pwa-register` to a no-op module. The
+ * client only imports it behind the `__SLIDEV_FEATURE_PWA__` guard (stripped
+ * from the build when off), but the guarded dynamic import must still resolve
+ * during dev — without pulling in the optional `vite-plugin-pwa` dependency.
+ */
+function createPWARegisterStubPlugin(): Plugin {
+  const VIRTUAL_ID = 'virtual:pwa-register'
+  const RESOLVED_ID = `\0${VIRTUAL_ID}`
+  return {
+    name: 'slidev:pwa-register-stub',
+    resolveId(id) {
+      return id === VIRTUAL_ID ? RESOLVED_ID : undefined
+    },
+    load(id) {
+      if (id === RESOLVED_ID)
+        return 'export function registerSW() { return () => Promise.resolve() }'
+    },
+  }
 }
diff --git a/packages/slidev/package.json b/packages/slidev/package.json
@@ -41,11 +41,15 @@
     "start": "tsx node/cli.ts"
   },
   "peerDependencies": {
-    "playwright-chromium": "^1.10.0"
+    "playwright-chromium": "^1.10.0",
+    "vite-plugin-pwa": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "playwright-chromium": {
       "optional": true
+    },
+    "vite-plugin-pwa": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -115,7 +119,6 @@
     "uqr": "catalog:prod",
     "vite": "catalog:prod",
     "vite-plugin-inspect": "catalog:prod",
-    "vite-plugin-pwa": "catalog:prod",
     "vite-plugin-remote-assets": "catalog:prod",
     "vite-plugin-static-copy": "catalog:prod",
     "vite-plugin-vue-server-ref": "catalog:prod",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
