tessl/npm-vuepress--plugin-pwa

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

VuePress PWA Plugin

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

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;
}