tessl/npm-workbox-precaching

This module efficiently precaches assets for Progressive Web Apps and service workers.

—

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

Workbox Precaching

Name: tessl/npm-workbox-precaching
Author: tessl

Workbox Precaching efficiently precaches assets for Progressive Web Apps (PWAs) and service workers. It provides a comprehensive API for caching resources during service worker installation and serving them from the cache to handle network requests, enabling reliable offline functionality and improved performance.

Package Information

Package Name: workbox-precaching
Package Type: npm
Language: TypeScript
Installation: npm install workbox-precaching

Core Imports

import { precacheAndRoute, PrecacheController } from "workbox-precaching";

For CommonJS:

const { precacheAndRoute, PrecacheController } = require("workbox-precaching");

Basic Usage

import { precacheAndRoute } from "workbox-precaching";

// Simple setup: precache assets and add route in one call
precacheAndRoute([
  { url: "/index.html", revision: "abc123" },
  { url: "/styles.css", revision: "def456" },
  "/static/logo.png", // URLs without revision use the URL as the cache key
]);

// This is equivalent to:
// precache(entries);
// addRoute();

Architecture

Workbox Precaching is built around several key components:

High-level Functions: precacheAndRoute(), precache(), addRoute() for simple setup
Controller API: PrecacheController class for fine-grained control over caching behavior
Route System: PrecacheRoute and PrecacheStrategy for custom routing and caching strategies
Utility Functions: Helper functions for cache key management and request matching
Plugin System: Extensible architecture with addPlugins() and PrecacheFallbackPlugin
Cache Management: Automatic cleanup of outdated caches and integrity checking

Capabilities

Simple Setup Functions

High-level functions for quick precaching setup that handle the most common use cases.

function precacheAndRoute(
  entries: Array<PrecacheEntry | string>,
  options?: PrecacheRouteOptions
): void;

function precache(entries: Array<PrecacheEntry | string>): void;

function addRoute(options?: PrecacheRouteOptions): void;

Simple Setup

Advanced Controller

The PrecacheController class provides fine-grained control over precaching behavior with methods for installation, activation, and cache management.

class PrecacheController {
  constructor(options?: PrecacheControllerOptions);
  
  precache(entries: Array<PrecacheEntry | string>): void;
  install(event: ExtendableEvent): Promise<InstallResult>;
  activate(event: ExtendableEvent): Promise<CleanupResult>;
}

Advanced Controller

Route and Strategy Classes

Custom route and strategy classes for implementing specific caching behaviors and request handling patterns.

class PrecacheRoute extends Route {
  constructor(
    precacheController: PrecacheController,
    options?: PrecacheRouteOptions
  );
}

class PrecacheStrategy extends Strategy {
  constructor(options?: PrecacheStrategyOptions);
}

Route and Strategy

Utility Functions

Helper functions for cache key management, request matching, and handler creation.

function getCacheKeyForURL(url: string): string | undefined;

function matchPrecache(request: string | Request): Promise<Response | undefined>;

function createHandlerBoundToURL(url: string): RouteHandlerCallback;

Utilities

Plugin and Cleanup

Plugin system for extending functionality and cleanup utilities for cache maintenance.

function addPlugins(plugins: WorkboxPlugin[]): void;

function cleanupOutdatedCaches(): void;

class PrecacheFallbackPlugin implements WorkboxPlugin {
  constructor(options: {
    fallbackURL: string;
    precacheController?: PrecacheController;
  });
}

Plugins and Cleanup

Core Types

interface PrecacheEntry {
  url: string;
  revision?: string | null;
  integrity?: string;
}

interface PrecacheRouteOptions {
  directoryIndex?: string;
  ignoreURLParametersMatching?: RegExp[];
  cleanURLs?: boolean;
  urlManipulation?: urlManipulation;
}

type urlManipulation = ({ url }: { url: URL }) => URL[];

interface InstallResult {
  updatedURLs: string[];
  notUpdatedURLs: string[];
}

interface CleanupResult {
  deletedCacheRequests: string[];
}

interface PrecacheControllerOptions {
  cacheName?: string;
  plugins?: WorkboxPlugin[];
  fallbackToNetwork?: boolean;
}

interface PrecacheStrategyOptions {
  cacheName?: string;
  plugins?: WorkboxPlugin[];
  fetchOptions?: RequestInit;
  matchOptions?: CacheQueryOptions;
  fallbackToNetwork?: boolean;
}

External Types

These types are imported from other Workbox packages:

// From workbox-core
interface WorkboxPlugin {
  cacheKeyWillBeUsed?: (options: any) => Promise<string> | string;
  cacheWillUpdate?: (options: any) => Promise<Response | null> | Response | null;
  cacheDidUpdate?: (options: any) => Promise<void> | void;
  cachedResponseWillBeUsed?: (options: any) => Promise<Response | null> | Response | null;
  requestWillFetch?: (options: any) => Promise<Request> | Request;
  fetchDidSucceed?: (options: any) => Promise<Response> | Response;
  fetchDidFail?: (options: any) => Promise<void> | void;
  handlerWillStart?: (options: any) => Promise<void> | void;
  handlerWillRespond?: (options: any) => Promise<Response> | Response;
  handlerDidRespond?: (options: any) => Promise<void> | void;
  handlerDidComplete?: (options: any) => Promise<void> | void;
  handlerDidError?: (options: any) => Promise<Response | undefined> | Response | undefined;
}

type RouteHandlerCallback = (options: {
  request: Request;
  event: ExtendableEvent;
}) => Promise<Response> | Response;

// From workbox-routing
class Route {
  constructor(match: any, handler: any, method?: string);
}

// From workbox-strategies  
class Strategy {
  constructor(options?: any);
}