tessl/npm-vuepress--plugin-pwa

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

—

Pending

Overview

Eval results

Files

Service Worker Events

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

Client-side service worker event handling and update management for PWA functionality, including event bus communication and update activation.

Capabilities

SWUpdateEvent Class

Event wrapper for service worker registration updates that provides methods for checking updates and activating new service workers.

/**
 * Service worker update event wrapper
 * @param {ServiceWorkerRegistration} registration - Service worker registration object
 */
class SWUpdateEvent {
  constructor(registration: ServiceWorkerRegistration);
  
  /** Service worker registration instance */
  readonly registration: ServiceWorkerRegistration;
  
  /**
   * Check if the new service worker exists or not
   * @returns {Promise<ServiceWorkerRegistration>} Promise resolving to updated registration
   */
  update(): Promise<ServiceWorkerRegistration>;
  
  /**
   * Activate new service worker to work with new data
   * Triggers skipWaiting() on the waiting service worker
   * @returns {Promise<any>} Promise resolving when skip waiting is complete
   */
  skipWaiting(): Promise<any>;
}

Usage Examples:

import event from '@sw-event';

// Listen for service worker updates
event.$on('sw-updated', (updateEvent) => {
  console.log('New service worker available');
  
  // Check for updates
  updateEvent.update().then(() => {
    console.log('Update check completed');
  });
  
  // Activate new service worker immediately
  updateEvent.skipWaiting().then(() => {
    // Reload page to use new service worker
    location.reload(true);
  });
});

Service Worker Event Bus

Global Vue event bus for managing service worker lifecycle events and communication between components.

/**
 * Global event bus for service worker events
 * Exported from '@sw-event' alias
 */
const swEventBus: Vue;

Available Events:

interface ServiceWorkerEvents {
  /** Service worker is active and ready */
  'sw-ready': () => void;
  
  /** Content has been cached for offline use */
  'sw-cached': (event: SWUpdateEvent) => void;
  
  /** New content is available for update */
  'sw-updated': (event: SWUpdateEvent) => void;
  
  /** App is running in offline mode */
  'sw-offline': () => void;
  
  /** Error during service worker registration */
  'sw-error': (error: Error) => void;
}

Event Usage Examples:

import event from '@sw-event';

// Service worker is ready
event.$on('sw-ready', () => {
  console.log('[vuepress:sw] Service worker is active.');
});

// Content cached for offline use
event.$on('sw-cached', (updateEvent) => {
  console.log('[vuepress:sw] Content has been cached for offline use.');
  // updateEvent is an instance of SWUpdateEvent
});

// New content available
event.$on('sw-updated', (updateEvent) => {
  console.log('[vuepress:sw] Content updated.');
  // Show update notification or auto-update
  updateEvent.skipWaiting().then(() => {
    location.reload(true);
  });
});

// Offline mode detected
event.$on('sw-offline', () => {
  console.log('[vuepress:sw] No internet connection found. App is running in offline mode.');
  // Show offline indicator
});

// Service worker registration error
event.$on('sw-error', (error) => {
  console.error('[vuepress:sw] Error during service worker registration:', error);
  // Handle error gracefully
});

Service Worker Registration

Automatic service worker registration that occurs during client-side app enhancement.

/**
 * Service worker registration configuration
 * Automatically registered at router.onReady()
 */
interface ServiceWorkerRegistration {
  /** URL path to service worker file */
  url: string; // `${SW_BASE_URL}service-worker.js`
  
  /** Registration options */
  registrationOptions: {};
  
  /** Lifecycle event handlers */
  handlers: {
    ready(): void;
    cached(registration: ServiceWorkerRegistration): void;
    updated(registration: ServiceWorkerRegistration): void;
    offline(): void;
    error(error: Error): void;
  };
}

The service worker is automatically registered in production mode when SW_ENABLED is true. Registration happens after the Vue router is ready to ensure proper initialization.

Production Only: Service worker registration is automatically disabled in development mode (process.env.NODE_ENV !== 'production') to prevent caching issues during development.

Skip-Waiting Message Channel

Communication mechanism between main thread and service worker for immediate activation.

/**
 * Skip-waiting communication uses MessageChannel
 * Service worker listens for 'skip-waiting' message type
 */
interface SkipWaitingMessage {
  /** Message type identifier */
  type: 'skip-waiting';
}

interface SkipWaitingResponse {
  /** Error if skip-waiting failed, null on success */
  error: Error | null;
}

The skip-waiting functionality is handled automatically by the SWUpdateEvent.skipWaiting() method using MessageChannel communication.

Types

interface ServiceWorkerRegistration {
  /** Update the service worker registration */
  update(): Promise<ServiceWorkerRegistration>;
  /** Waiting service worker instance (if available) */
  waiting?: ServiceWorker;
  /** Active service worker instance (if available) */
  active?: ServiceWorker;
  /** Installing service worker instance (if available) */
  installing?: ServiceWorker;
}

interface ServiceWorker {
  /** Post message to service worker */
  postMessage(message: any, transfer?: Transferable[]): void;
  /** Service worker state */
  state: 'installing' | 'installed' | 'activating' | 'activated' | 'redundant';
}

Install with Tessl CLI

npx tessl i tessl/npm-vuepress--plugin-pwa

docs

index.md

plugin-configuration.md

service-worker-events.md

update-notifications.md

tile.json

tessl/npm-vuepress--plugin-pwa