or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-workbox-broadcast-update

A service worker helper library that uses the Broadcast Channel API to announce when a cached response has updated

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/workbox-broadcast-update@7.3.x

To install, run

npx @tessl/cli install tessl/npm-workbox-broadcast-update@7.3.0

Workbox Broadcast Update

A service worker helper library that uses the Broadcast Channel API to announce when a cached response has been updated. This library enables applications to automatically notify users when cached content is refreshed, providing real-time feedback about content freshness in cache-first strategies.

Package Information

Package Name: workbox-broadcast-update
Package Type: npm
Language: TypeScript
Installation: npm install workbox-broadcast-update

Core Imports

import { 
  BroadcastCacheUpdate, 
  BroadcastCacheUpdateOptions,
  BroadcastUpdatePlugin, 
  responsesAreSame 
} from "workbox-broadcast-update";

For CommonJS:

const { 
  BroadcastCacheUpdate, 
  BroadcastUpdatePlugin, 
  responsesAreSame 
} = require("workbox-broadcast-update");

Basic Usage

import { BroadcastUpdatePlugin } from "workbox-broadcast-update";
import { StaleWhileRevalidate } from "workbox-strategies";

// Use as a plugin with Workbox strategies
const strategy = new StaleWhileRevalidate({
  cacheName: "api-cache",
  plugins: [
    new BroadcastUpdatePlugin({
      headersToCheck: ["etag", "last-modified"],
    }),
  ],
});

// Direct usage for manual cache updates
import { BroadcastCacheUpdate } from "workbox-broadcast-update";

const broadcastUpdate = new BroadcastCacheUpdate({
  headersToCheck: ["content-length", "etag"],
  notifyAllClients: true,
});

await broadcastUpdate.notifyIfUpdated({
  cacheName: "my-cache",
  oldResponse,
  newResponse,
  request,
  event,
});

Architecture

Workbox Broadcast Update is built around several key components:

BroadcastCacheUpdate: Core class that compares responses and sends broadcast messages
BroadcastUpdatePlugin: Workbox plugin that integrates with caching strategies
Response Comparison: Efficient header-based comparison to detect content changes
Broadcast Channel API: Uses native web APIs to communicate between service worker and main thread
Client Targeting: Supports both all-client and single-client notification modes

The library uses header comparison rather than full response body comparison for efficiency, making it suitable for high-traffic applications.

Capabilities

Cache Update Broadcasting

Core functionality for detecting and broadcasting cache updates using the Broadcast Channel API.

class BroadcastCacheUpdate {
  /**
   * Creates a new BroadcastCacheUpdate instance
   * @param options - Configuration options for the broadcast update behavior
   */
  constructor(options?: BroadcastCacheUpdateOptions);

  /**
   * Compares two responses and broadcasts an update message if they differ
   * @param options - Parameters containing old/new responses and cache metadata
   * @returns Promise that resolves when broadcast is complete
   */
  notifyIfUpdated(options: CacheDidUpdateCallbackParam): Promise<void>;
}

interface BroadcastCacheUpdateOptions {
  /** Headers to check for differences (default: ['content-length', 'etag', 'last-modified']) */
  headersToCheck?: string[];
  /** Custom function to generate message payload */
  generatePayload?: (options: CacheDidUpdateCallbackParam) => Record<string, any>;
  /** Whether to notify all clients or just the requesting client (default: true) */
  notifyAllClients?: boolean;
}

interface CacheDidUpdateCallbackParam {
  /** Name of the cache being updated */
  cacheName: string;
  /** The previous cached response */
  oldResponse?: Response;
  /** The new response being cached */
  newResponse: Response;
  /** The request that triggered the update */
  request: Request;
  /** The event that triggered the update */
  event?: ExtendableEvent;
}

Workbox Plugin Integration

Plugin that automatically broadcasts cache updates when integrated with Workbox caching strategies.

class BroadcastUpdatePlugin implements WorkboxPlugin {
  /**
   * Creates a new BroadcastUpdatePlugin instance
   * @param options - Configuration options passed to internal BroadcastCacheUpdate
   */
  constructor(options?: BroadcastCacheUpdateOptions);

  /**
   * Workbox plugin lifecycle method triggered when cache entries are updated
   * @param options - Cache update parameters from Workbox
   */
  cacheDidUpdate: WorkboxPlugin['cacheDidUpdate'];
}

interface WorkboxPlugin {
  cacheDidUpdate?: (param: CacheDidUpdateCallbackParam) => Promise<void> | void;
}

Response Comparison Utility

Utility function for comparing Response objects based on specific headers.

/**
 * Compares two Response objects by checking specified headers
 * @param firstResponse - First response to compare
 * @param secondResponse - Second response to compare  
 * @param headersToCheck - Array of header names to check for differences
 * @returns True if responses are considered the same, false otherwise
 */
function responsesAreSame(
  firstResponse: Response,
  secondResponse: Response,
  headersToCheck: string[]
): boolean;

Types

Configuration Options

Configuration interface for BroadcastCacheUpdate behavior.

interface BroadcastCacheUpdateOptions {
  /** Headers to check for differences (default: ['content-length', 'etag', 'last-modified']) */
  headersToCheck?: string[];
  /** Custom function to generate message payload */
  generatePayload?: (options: CacheDidUpdateCallbackParam) => Record<string, any>;
  /** Whether to notify all clients or just the requesting client (default: true) */
  notifyAllClients?: boolean;
}

Message Format

When a cache update is detected, the library broadcasts a message with the following structure:

interface BroadcastMessage {
  /** Always 'CACHE_UPDATED' */
  type: "CACHE_UPDATED";
  /** Always 'workbox-broadcast-update' */
  meta: "workbox-broadcast-update";
  /** Update details - customizable via generatePayload option */
  payload: {
    /** Name of the updated cache */
    cacheName: string;
    /** URL of the updated resource */
    updatedURL: string;
    /** Additional custom fields from generatePayload function */
    [key: string]: any;
  };
}

Error Handling

The library includes built-in error handling for common scenarios:

Invalid Response Types: Throws WorkboxError for non-Response objects in development
Missing Required Parameters: Validates cacheName, newResponse, and request parameters
Missing Headers: Returns true (no update) when none of the specified headers are present
Safari Compatibility: Includes timeout handling for Safari's postMessage limitations

Usage Examples

Basic Plugin Usage

import { BroadcastUpdatePlugin } from "workbox-broadcast-update";
import { registerRoute } from "workbox-routing";
import { StaleWhileRevalidate } from "workbox-strategies";

// Register a route with automatic broadcast updates
registerRoute(
  ({ request }) => request.destination === "document",
  new StaleWhileRevalidate({
    cacheName: "pages-cache",
    plugins: [
      new BroadcastUpdatePlugin({
        headersToCheck: ["etag", "last-modified"],
      }),
    ],
  })
);

Custom Payload Generation

import { BroadcastCacheUpdate } from "workbox-broadcast-update";

const broadcastUpdate = new BroadcastCacheUpdate({
  generatePayload: ({ cacheName, request, newResponse }) => ({
    cacheName,
    updatedURL: request.url,
    timestamp: Date.now(),
    responseSize: newResponse.headers.get("content-length"),
    contentType: newResponse.headers.get("content-type"),
  }),
});

Single Client Notification

import { BroadcastUpdatePlugin } from "workbox-broadcast-update";

// Only notify the client that made the original request
const plugin = new BroadcastUpdatePlugin({
  notifyAllClients: false,
});

Manual Response Comparison

import { responsesAreSame } from "workbox-broadcast-update";

const hasChanged = !responsesAreSame(
  oldResponse,
  newResponse,
  ["etag", "content-length", "last-modified"]
);

if (hasChanged) {
  console.log("Content has been updated!");
}

Listening for Updates in Client Code

// In your main thread (window) code
navigator.serviceWorker.addEventListener("message", (event) => {
  if (
    event.data.type === "CACHE_UPDATED" &&
    event.data.meta === "workbox-broadcast-update"
  ) {
    const { cacheName, updatedURL } = event.data.payload;
    
    // Show notification to user
    showUpdateNotification(`New content available for ${updatedURL}`);
    
    // Optionally reload the page
    if (confirm("New content is available. Reload now?")) {
      window.location.reload();
    }
  }
});