CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-workbox-precaching

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

Overview
Eval results
Files

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

Install with Tessl CLI

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