or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-controller.mdindex.mdplugins-cleanup.mdroute-strategy.mdsimple-setup.mdutilities.md
tile.json

tessl/npm-workbox-precaching

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/workbox-precaching@7.3.x

To install, run

npx @tessl/cli install tessl/npm-workbox-precaching@7.3.0

index.mddocs/

Workbox Precaching

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