vite-plugin-pwa-manifest

Generate a PWA web app manifest for any Vite app — env-aware build metadata, a fully-typed config, and a no-store dev preview that honors your Vite base. Zero dependencies, ESM + CJS.

Features

• 🧾 Generates a valid manifest.json at build time (emitted to your build outDir).
• 💾 Optional on-disk mirror (outputDir) for static hosting / CDNs — written only when changed.
• 🧪 Dev preview with no-store + weak ETag/304, served at the correct route under a custom base.
• 🏷️ Build metadata out of the box: version (git tag/commit), pkgVersion, buildTime, mode.
• 🎛️ Full transform(json, { mode }) hook for complete control.
• 🖼️ Icon normalization + de-duplication, with a one-time warning when no maskable icon is present.
• 🟢 Zero runtime dependencies.

Installation

npm i -D vite-plugin-pwa-manifest
# or: pnpm add -D vite-plugin-pwa-manifest
# or: yarn add -D vite-plugin-pwa-manifest

Requires Node ≥ 18 and Vite ≥ 4.

Usage

// vite.config.ts
import { defineConfig } from 'vite';
import generateManifest from 'vite-plugin-pwa-manifest';

export default defineConfig({
  plugins: [
    generateManifest({
      name: 'My App',
      short_name: 'App',
      description: 'Example PWA with Vite',
      theme_color: '#0a131b',
      icons: [
        { src: '/icons/icon-192x192.png', sizes: '192x192', type: 'image/png', purpose: 'any maskable' },
        { src: '/icons/icon-512x512.png', sizes: '512x512', type: 'image/png', purpose: 'any maskable' },
      ],
      outputDir: 'public', // optional: also write public/manifest.json
      transform(json, { mode }) {
        if (mode === 'development') json.name = 'My App (dev)';
        return json;
      },
    }),
  ],
});

Reference it from your HTML:

<link rel="manifest" href="/manifest.json" />

| Phase | Behavior | |-------|----------| | dev (vite) | Served at the manifest.json route under your Vite base with Cache-Control: no-store + weak ETag (304 on If-None-Match). | | build (vite build) | Emitted as a build asset to the root of your build outDir. | | outputDir | Also written to disk (dev & build), skipped when unchanged. |

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | filename | string | "manifest.json" | Output filename. | | outputDir | string \| false | false | Mirror the manifest to this directory on disk. | | name / short_name | string | "My App" / "App" | Display names. | | description | string | — | App description. | | lang / dir | string / "ltr" \| "rtl" | "en" / "ltr" | Language & direction. | | start_url / scope / id | string | "/" | Each is normalized to a leading slash. | | display | "standalone" \| "fullscreen" \| "minimal-ui" \| "browser" | "standalone" | Display mode. | | orientation | "any" \| "portrait" \| "landscape" | — | Orientation. | | background_color | string | falls back to theme_color | Splash background. | | theme_color | string | "#0a131b" | Theme color. | | categories | string[] | — | App store categories. | | prefer_related_applications / related_applications | — | — | Native app hints. | | protocol_handlers | Array<{ protocol; url }> | — | Protocol handlers. | | icons | ManifestIcon[] | 192/512 maskable | Icons (normalized + de-duped). | | screenshots | Screenshot[] | — | Screenshots. | | extra | Record<string, unknown> | — | Extra fields merged into the manifest. | | includeBuildMeta | boolean | true | Add pkgVersion, version, buildTime, mode. | | transform | (json, { mode }) => json | — | Final transform over the assembled manifest. |

Note: start_url, scope, and id are always normalized to begin with /. Fields left undefined are omitted from the output.

Types

type ManifestIcon = {
  src: string;
  sizes: string;
  type?: string;
  purpose?: 'any' | 'maskable' | 'monochrome' | 'any maskable';
};

type Screenshot = {
  src: string;
  sizes?: string;
  type?: string;
  label?: string;
  form_factor?: 'wide' | 'narrow';
};

Build metadata

With includeBuildMeta (default true) the plugin appends:

| Field | Source | |-------|--------| | version | nearest git tag, else git describe, else short commit, else pkgVersion. | | pkgVersion | version from your package.json. | | buildTime | ISO timestamp of the build. | | mode | "development" in dev, "production" in build. |

Git is detected via a statically-imported execSync (not a dynamic require), so detection works correctly in both the ESM and CJS builds. Outside a git work tree these fields simply fall back to pkgVersion.

Example output

{
  "lang": "en",
  "dir": "ltr",
  "name": "My App",
  "short_name": "App",
  "description": "Example PWA with Vite",
  "start_url": "/",
  "scope": "/",
  "id": "/",
  "display": "standalone",
  "background_color": "#0a131b",
  "theme_color": "#0a131b",
  "icons": [
    { "src": "/icons/icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any maskable" },
    { "src": "/icons/icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
  ],
  "pkgVersion": "1.4.0",
  "version": "v1.4.0",
  "buildTime": "2025-09-09T13:45:00.000Z",
  "mode": "production"
}

License

MIT © dev.zarghami