tessl/npm-vite-plugin-pwa

Zero-config PWA plugin for Vite that enables offline functionality, service workers, and web app manifest generation.

—

Pending

Overview

Eval results

Files

Plugin Configuration

Name: tessl/npm-vite-plugin-pwa
Author: tessl

Configuration options and setup for the Vite Plugin PWA, including service worker strategies, manifest options, and development settings.

Capabilities

Main Plugin Function

Creates the Vite Plugin PWA with specified configuration options.

/**
 * Creates a Vite Plugin PWA with the specified configuration
 * @param userOptions - Partial PWA configuration options
 * @returns Array of Vite plugins for PWA functionality
 */
function VitePWA(userOptions?: Partial<VitePWAOptions>): Plugin[];

Usage Example:

import { VitePWA } from "vite-plugin-pwa";

// Basic configuration
const pwaPlugin = VitePWA({
  registerType: "autoUpdate",
  workbox: {
    globPatterns: ["**/*.{js,css,html,ico,png,svg}"],
  },
});

// Advanced configuration with custom service worker
const advancedPwaPlugin = VitePWA({
  strategies: "injectManifest",
  srcDir: "src",
  filename: "my-sw.ts",
  injectManifest: {
    swSrc: "src/my-sw.ts",
    swDest: "dist/my-sw.js", 
  },
  manifest: {
    name: "My Advanced PWA",
    short_name: "AdvancedPWA",
    icons: [
      {
        src: "icon-192.png",
        sizes: "192x192",
        type: "image/png",
      },
    ],
  },
});

Service Worker Strategies

Configure how the service worker is generated and managed.

type ServiceWorkerStrategy = 'generateSW' | 'injectManifest';

interface GenerateSWConfig {
  strategies: 'generateSW';
  workbox: Partial<GenerateSWOptions>;
}

interface InjectManifestConfig {
  strategies: 'injectManifest';
  injectManifest: Partial<CustomInjectManifestOptions>;
}

generateSW Strategy:

VitePWA({
  strategies: "generateSW", // default
  workbox: {
    globPatterns: ["**/*.{js,css,html,ico,png,svg}"],
    runtimeCaching: cachePreset, // Use built-in cache preset
    cleanupOutdatedCaches: true,
    skipWaiting: true,
    clientsClaim: true,
  },
});

injectManifest Strategy:

VitePWA({
  strategies: "injectManifest",
  srcDir: "src",
  filename: "custom-sw.ts",
  injectManifest: {
    swSrc: "src/custom-sw.ts",
    swDest: "dist/custom-sw.js",
    rollupFormat: "es",
    minify: true,
    sourcemap: true,
  },
});

Registration Configuration

Control how the service worker is registered in the client application.

type RegisterType = 'prompt' | 'autoUpdate';
type InjectRegister = 'inline' | 'script' | 'script-defer' | 'auto' | null | false;

interface RegistrationOptions {
  registerType?: RegisterType;
  injectRegister?: InjectRegister;
  scope?: string;
  immediate?: boolean;
}

Usage Examples:

// Auto-update mode - automatically updates when new SW is available
VitePWA({
  registerType: "autoUpdate",
  injectRegister: "auto", // default
});

// Prompt mode - user confirmation required for updates
VitePWA({
  registerType: "prompt", // default
  injectRegister: "script-defer", // deferred script injection
});

// Manual registration - no automatic injection
VitePWA({
  injectRegister: false, // Use virtual modules for manual control
});

Web App Manifest Configuration

Configure the PWA manifest file for app metadata and display options.

interface ManifestOptions {
  name: string;
  short_name: string;
  description?: string;
  icons: IconResource[];
  start_url?: string;
  scope?: string;
  id?: string;
  display?: Display;
  display_override?: DisplayOverride[];
  orientation?: 'any' | 'natural' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'portrait' | 'portrait-primary' | 'portrait-secondary';
  theme_color?: string;
  background_color?: string;
  lang?: string;
  dir?: 'ltr' | 'rtl';
  categories?: string[];
  screenshots?: ScreenshotResource[];
  shortcuts?: ShortcutResource[];
  related_applications?: RelatedApplication[];
  prefer_related_applications?: boolean;
  protocol_handlers?: ProtocolHandler[];
  file_handlers?: FileHandler[];
  share_target?: ShareTarget;
  handle_links?: 'auto' | 'preferred' | 'not-preferred';
  launch_handler?: LaunchHandler;
  edge_side_panel?: EdgeSidePanel;
  scope_extensions?: ScopeExtension[];
}

interface IconResource {
  src: string;
  sizes?: string;
  type?: string;
  purpose?: StringLiteralUnion<IconPurpose> | IconPurpose[];
}

type Display = 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser';
type DisplayOverride = Display | 'window-controls-overlay';
type IconPurpose = 'monochrome' | 'maskable' | 'any';

Usage Example:

VitePWA({
  manifest: {
    name: "My Progressive Web App",
    short_name: "MyPWA",
    description: "A comprehensive PWA built with Vite",
    theme_color: "#ffffff",
    background_color: "#ffffff",
    display: "standalone",
    orientation: "portrait",
    scope: "/",
    start_url: "/",
    icons: [
      {
        src: "pwa-64x64.png",
        sizes: "64x64",
        type: "image/png",
      },
      {
        src: "pwa-192x192.png",
        sizes: "192x192",
        type: "image/png",
      },
      {
        src: "pwa-512x512.png",
        sizes: "512x512",
        type: "image/png",
        purpose: "any",
      },
      {
        src: "maskable-icon-512x512.png",
        sizes: "512x512",
        type: "image/png",
        purpose: "maskable",
      },
    ],
    screenshots: [
      {
        src: "screenshot-wide.png",
        sizes: "1280x720",
        type: "image/png",
        form_factor: "wide",
      },
    ],
    shortcuts: [
      {
        name: "Dashboard",
        short_name: "Dashboard",
        description: "View the dashboard",
        url: "/dashboard",
        icons: [{ src: "dashboard-icon.png", sizes: "192x192" }],
      },
    ],
  },
});

Development Options

Configure PWA behavior during development.

interface DevOptions {
  enabled?: boolean;
  suppressWarnings?: boolean;
  navigateFallback?: string;
  navigateFallbackAllowlist?: RegExp[];
  navigateFallbackDenylist?: RegExp[];
  type?: 'classic' | 'module';
  webManifestUrl?: string;
}

Usage Example:

VitePWA({
  devOptions: {
    enabled: true, // Enable PWA in development
    suppressWarnings: true,
    navigateFallback: "index.html",
    type: "module",
  },
});

PWA Assets Generation

Configure automatic generation of PWA icons and splash screens.

interface PWAAssetsOptions {
  disabled?: boolean;
  config?: string | boolean;
  preset?: false | BuiltInPreset | Preset;
  image?: string;
  htmlPreset?: HtmlLinkPreset;
  includeHtmlHeadLinks?: boolean;
  overrideManifestIcons?: boolean;
  injectThemeColor?: boolean;
  integration?: PWAAssetsIntegration;
}

interface PWAAssetsIntegration {
  baseUrl?: string;
  publicDir?: string;
  outDir?: string;
}

Usage Example:

VitePWA({
  pwaAssets: {
    preset: "minimal-2023",
    image: "public/logo.svg",
    htmlPreset: "2023",
    includeHtmlHeadLinks: true,
    overrideManifestIcons: false,
    injectThemeColor: true,
  },
});

Integration Hooks

Provide custom integration hooks for advanced use cases.

interface PWAIntegration {
  beforeBuildServiceWorker?: (options: ResolvedVitePWAOptions) => void | Promise<void>;
  closeBundleOrder?: 'pre' | 'post' | null;
  configureOptions?: (viteOptions: ResolvedConfig, options: Partial<VitePWAOptions>) => void | Promise<void>;
  configureCustomSWViteBuild?: (options: InlineConfig) => void | Promise<void>;
}

Constants

Cache Preset

Pre-configured runtime caching strategies for common asset types.

const cachePreset: RuntimeCaching[];

The cache preset includes optimized caching strategies for:

Google Fonts (CacheFirst, 365 days)
Font files (StaleWhileRevalidate, 7 days)
Images (StaleWhileRevalidate, 24 hours)
JavaScript files (StaleWhileRevalidate, 24 hours)
CSS files (StaleWhileRevalidate, 24 hours)
JSON/XML/CSV data (NetworkFirst, 24 hours)
API calls (NetworkFirst, 24 hours, 10s timeout)
Other resources (NetworkFirst, 24 hours, 10s timeout)

Default Inject Manifest Vite Plugins

Default list of Vite plugin IDs used when building custom service workers with injectManifest strategy.

const defaultInjectManifestVitePlugins: string[];

Includes plugins: alias, commonjs, vite:resolve, vite:esbuild, replace, vite:define, rollup-plugin-dynamic-import-variables, vite:esbuild-transpile, vite:json, vite:terser.

Install with Tessl CLI