or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdplugin-configuration.mdservice-worker-events.mdupdate-notifications.md
tile.json

tessl/npm-vuepress--plugin-pwa

Progressive Web App plugin for VuePress that adds service worker support and offline functionality

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vuepress/plugin-pwa@1.9.x

To install, run

npx @tessl/cli install tessl/npm-vuepress--plugin-pwa@1.9.0

index.mddocs/

VuePress PWA Plugin

VuePress PWA Plugin (@vuepress/plugin-pwa) adds Progressive Web App functionality to VuePress sites by providing service worker generation, offline caching, and update notifications. It enables VuePress documentation sites to work offline and provide app-like experiences for users. The plugin is only active in production mode for performance and development workflow reasons.

Package Information

  • Package Name: @vuepress/plugin-pwa
  • Package Type: npm (VuePress Plugin)
  • Language: JavaScript
  • Installation: npm install @vuepress/plugin-pwa
  • Dependencies: register-service-worker ^1.7.0, workbox-build ^4.3.1

Core Imports

const pwaPlugin = require('@vuepress/plugin-pwa');

For VuePress configuration:

// .vuepress/config.js
module.exports = {
  plugins: [
    ['@vuepress/pwa', {
      serviceWorker: true,
      updatePopup: true
    }]
  ]
}

Basic Usage

// .vuepress/config.js
module.exports = {
  plugins: [
    ['@vuepress/pwa', {
      serviceWorker: true,
      updatePopup: {
        message: "New content is available.",
        buttonText: "Refresh"
      },
      generateSWConfig: {
        globPatterns: [
          '**/*.{js,css,html,png,jpg,jpeg,gif,svg,woff,woff2,eot,ttf,otf}'
        ]
      }
    }]
  ]
}

Architecture

The VuePress PWA Plugin is built around several key components:

  • Plugin Configuration: Main plugin function that configures VuePress for PWA functionality
  • Service Worker Generation: Uses Workbox to automatically generate service workers for offline caching
  • Client-Side Enhancement: Registers service workers and handles PWA events in the browser
  • Update Notifications: Provides user interface components for notifying users of updates
  • Event System: Client-side event bus for managing service worker lifecycle events
  • Google Analytics Integration: Automatic error reporting to Google Analytics when GA_ID is available

Capabilities

Plugin Configuration

Core plugin function that adds PWA functionality to VuePress sites with configurable options for service worker behavior and update notifications.

/**
 * VuePress PWA Plugin
 * @param {PluginConfig4PWA} options - Plugin configuration options (default: {})
 * @param {VuePressContext} context - VuePress build context
 * @returns {VuePressPlugin} VuePress plugin object
 */
function pwaPlugin(options, context): VuePressPlugin;

interface PluginConfig4PWA {
  /** Enable/disable service worker generation (default: true) */
  serviceWorker?: boolean;
  /** Enable update popup notifications (default: false) */
  updatePopup?: boolean | UpdatePopupConfig;
  /** Name of popup component to use (default: 'SWUpdatePopup') */
  popupComponent?: string;
  /** Configuration passed to workbox-build for service worker generation */
  generateSWConfig?: WorkboxConfig;
}

interface UpdatePopupConfig {
  /** Update notification message (default: 'New content is available.') */
  message?: string;
  /** Refresh button text (default: 'Refresh') */
  buttonText?: string;
  /** Localized messages for different routes */
  [locale: string]: {
    message: string;
    buttonText: string;
  };
}

interface VuePressPlugin {
  alias: Record<string, string>;
  define: () => Record<string, any>;
  globalUIComponents?: string;
  enhanceAppFiles: string;
  generated: () => Promise<void>;
}

Plugin Configuration

Service Worker Events

Client-side service worker event handling and update management for PWA functionality.

class SWUpdateEvent {
  constructor(registration: ServiceWorkerRegistration);
  /** Check if the new service worker exists or not */
  update(): Promise<ServiceWorkerRegistration>;
  /** Activate new service worker to work with new data */
  skipWaiting(): Promise<any>;
}

Service Worker Events

Update Notifications

Vue component system for displaying service worker update notifications to users.

// Global event bus for service worker events
const swEventBus: Vue;

// Default popup component
const SWUpdatePopup: VueComponent;

interface SWUpdatePopupProps {
  enabled: boolean;
  message: string;
  buttonText: string;
  reload: () => void;
}

Update Notifications

Types

interface ServiceWorkerRegistration {
  update(): Promise<ServiceWorkerRegistration>;
  waiting?: ServiceWorker;
}

interface WorkboxConfig {
  /** Destination path for generated service worker (auto-generated to outDir/service-worker.js) */
  swDest?: string;
  /** Directory to search for files to cache (defaults to VuePress outDir) */
  globDirectory?: string;
  /** Patterns matching files to cache (default: ['**/*.{js,css,html,png,jpg,jpeg,gif,svg,woff,woff2,eot,ttf,otf}']) */
  globPatterns?: string[];
  /** Maximum file size to include in precache (in bytes) */
  maximumFileSizeToCacheInBytes?: number;
  /** Runtime caching configuration for dynamic content */
  runtimeCaching?: RuntimeCachingEntry[];
  /** Skip waiting for service worker activation */
  skipWaiting?: boolean;
  /** Take control of clients immediately */
  clientsClaim?: boolean;
  /** Additional workbox-build configuration options */
  [key: string]: any;
}

interface RuntimeCachingEntry {
  /** URL pattern to match for caching */
  urlPattern: RegExp | string;
  /** Caching strategy to use */
  handler: 'CacheFirst' | 'NetworkFirst' | 'NetworkOnly' | 'CacheOnly' | 'StaleWhileRevalidate';
  /** Cache configuration options */
  options?: {
    cacheName?: string;
    expiration?: {
      maxEntries?: number;
      maxAgeSeconds?: number;
    };
  };
}

interface VuePressContext {
  /** Build output directory */
  outDir: string;
  /** Site base URL */
  base?: string;
}