slidevjs/slidev · error · Error

[slidev] Failed to load "${PWA_PACKAGE}", which is required

Error message

[slidev] Failed to load "${PWA_PACKAGE}", which is required by the "pwa" option.

What it means

Thrown by `resolveVitePWA` when Slidev's `pwa` option is enabled (per `options.data.config.pwa`) but `vite-plugin-pwa` cannot be loaded. The resolver first does an optional import, then prompts the user to install it, then retries; only if the factory `VitePWA` is still missing after both attempts does it throw. Note: when PWA is disabled (the default), Slidev never reaches this code — it returns a stub plugin instead, so this error is strictly opt-in.

Source

Thrown at packages/slidev/node/vite/pwa.ts:64

  })
}

/**
 * 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
    },

View on GitHub (pinned to 0d798ace58)

Solutions

1. Install the optional dependency: `npm i vite-plugin-pwa` (or pnpm/yarn equivalent), then restart.
2. If you did not intend to ship a PWA, disable the option — set `pwa: false` or remove the `pwa` key from your Slidev config / frontmatter `defaults`.
3. If installed but still failing, verify the package version exports `VitePWA` (named or via `default`); downgrade/upgrade to a compatible release and clear `node_modules`.
4. In non-interactive environments (CI, containers), pre-install `vite-plugin-pwa` before launching the dev/build so the prompt fallback is never relied upon.

Example fix

// before: headmatter enables pwa without the dep installed
---
pwa: true
---
// after (option A): install the dependency
//   npm i vite-plugin-pwa
// after (option B): turn the feature off
---
pwa: false
---

// Before enabling pwa, confirm the optional dependency is importable:
async function canLoadVitePWA(): Promise<boolean> {
  try {
    const mod = await import('vite-plugin-pwa')
    return Boolean(mod.VitePWA ?? mod.default?.VitePWA)
  } catch {
    return false
  }
}
// only set pwa: true when this returns true (or install it first).

import type VitePWAFactory from 'vite-plugin-pwa'
function isVitePWAFn(x: unknown): x is (opts: Record<string, any>) => unknown {
  return typeof x === 'function'
}

// Wrap your config build in CI so a missing PWA dep degrades gracefully:
try {
  await build({ pwa: true })
} catch (e) {
  if (String(e.message).includes('vite-plugin-pwa')) {
    console.warn('PWA disabled: vite-plugin-pwa missing. Building without PWA.')
    await build({ pwa: false })
  } else throw e
}

When it happens

Trigger: `pwa: true` (or matching mode) set in `slidev.config.ts` / headmatter while `vite-plugin-pwa` is not installed, and the interactive install prompt was declined, skipped (non-TTY/CI), or failed. Also fires if the package is installed but exports neither a named `VitePWA` nor a `default.VitePWA` (incompatible/corrupt version).

Common situations: Enabling `pwa: true` without installing the optional peer dependency; running Slidev in CI/Docker where `promptForOptionalInstallation` cannot get user input and the install silently no-ops; upgrading `vite-plugin-pwa` to a version that changed its export shape; a partially-installed/corrupt node_modules where the package directory exists but the entry file fails to load.

Related errors

• [slidev] "prism" support has been dropped. Please use "highl
• Invalid aspect ratio "${str}"
• [Slidev] ogImage: ${filename} not found
• [Slidev] Internal error: <script setup> block not found in s
• Package "${pkg}" not found in "${importer}"

AI-assisted analysis of slidevjs/slidev@0d798ace58 (2026-08-12). Data as JSON: /api/errors/a28568b234d0d5ad. Report an issue: GitHub.