Workbox Navigation Preload

Workbox Navigation Preload provides a simple interface for enabling and disabling Navigation Preload functionality in service workers. Navigation Preload is a browser optimization that allows network requests to be started in parallel with service worker activation, reducing the time between navigation startup and network response.

Package Information

• Package Name: workbox-navigation-preload
• Package Type: npm
• Language: TypeScript
• Installation: npm install workbox-navigation-preload
• Dependencies: workbox-core@7.3.0

Core Imports

import { enable, disable, isSupported } from "workbox-navigation-preload";

For CommonJS:

const { enable, disable, isSupported } = require("workbox-navigation-preload");

Basic Usage

import { enable, disable, isSupported } from "workbox-navigation-preload";

// Check if Navigation Preload is supported
if (isSupported()) {
  // Enable Navigation Preload with default header
  enable();
  
  // Or enable with custom header value
  enable("custom-preload-header");
  
  // Disable Navigation Preload
  disable();
} else {
  console.log("Navigation Preload not supported in this browser");
}

Architecture

Workbox Navigation Preload uses an event-driven architecture that integrates with the Service Worker lifecycle:

• Event Listener Pattern: Functions register activate event listeners on the service worker
• Lifecycle Integration: Uses event.waitUntil() to extend the activation lifecycle until operations complete
• Asynchronous Operations: All Navigation Preload API calls return promises that are properly awaited
• Graceful Degradation: Automatically checks browser support before attempting operations
• Development Logging: Provides runtime feedback via workbox-core logger utilities

Capabilities

Browser Support Detection

Checks whether Navigation Preload is supported in the current browser environment.

/**
 * Checks if Navigation Preload is supported in the current browser
 * @returns true if supported, false otherwise
 */
function isSupported(): boolean;

Usage Example:

import { isSupported } from "workbox-navigation-preload";

if (isSupported()) {
  console.log("Navigation Preload is available");
} else {
  console.log("Navigation Preload is not supported");
}

Enable Navigation Preload

Enables Navigation Preload functionality with optional custom header configuration.

/**
 * Enables Navigation Preload if supported by the browser
 * @param headerValue - Optional custom value for the Service-Worker-Navigation-Preload header
 */
function enable(headerValue?: string): void;

Usage Examples:

import { enable } from "workbox-navigation-preload";

// Enable with default header (Service-Worker-Navigation-Preload: true)
enable();

// Enable with custom header value
enable("my-custom-preload-value");

Behavior:

• Checks browser support via isSupported() before proceeding
• Registers an 'activate' event listener on the service worker
• Uses event.waitUntil() to extend the activation event lifecycle until completion
• Asynchronously calls self.registration.navigationPreload.enable()
• Sets custom header value if provided via self.registration.navigationPreload.setHeaderValue()
• Provides development-time logging via workbox-core/logger
• Silently does nothing if Navigation Preload is not supported

Disable Navigation Preload

Disables Navigation Preload functionality.

/**
 * Disables Navigation Preload if supported by the browser
 */
function disable(): void;

Usage Example:

import { disable } from "workbox-navigation-preload";

// Disable Navigation Preload
disable();

Behavior:

• Checks browser support via isSupported() before proceeding
• Registers an 'activate' event listener on the service worker
• Uses event.waitUntil() to extend the activation event lifecycle until completion
• Asynchronously calls self.registration.navigationPreload.disable()
• Provides development-time logging via workbox-core/logger
• Silently does nothing if Navigation Preload is not supported

Type Definitions

/**
 * Represents the current state of Navigation Preload
 */
interface NavigationPreloadState {
  enabled?: boolean;
  headerValue?: string;
}

/**
 * Interface for managing Navigation Preload functionality
 */
interface NavigationPreloadManager {
  disable(): Promise<void>;
  enable(): Promise<void>;
  getState(): Promise<NavigationPreloadState>;
  setHeaderValue(value: string): Promise<void>;
}

Global Type Extension:

declare global {
  interface ServiceWorkerRegistration {
    readonly navigationPreload: NavigationPreloadManager;
  }
}

/**
 * Service Worker global scope interface
 */
interface ServiceWorkerGlobalScope extends WorkerGlobalScope {
  registration: ServiceWorkerRegistration;
  addEventListener(type: 'activate', listener: (event: ExtendableEvent) => void): void;
}

/**
 * Extendable event interface for service worker lifecycle events
 */
interface ExtendableEvent extends Event {
  waitUntil(f: Promise<any>): void;
}

Service Worker Context Requirements

This library is designed to run in a Service Worker context and requires:

• self global scope (ServiceWorkerGlobalScope)
• self.registration property
• self.registration.navigationPreload API support

Error Handling

The library handles unsupported browsers gracefully:

• All functions check isSupported() before attempting operations
• No exceptions are thrown for unsupported browsers
• Development-time logging indicates support status
• Functions become no-ops when Navigation Preload is unavailable

Development vs Production Behavior

• Development: Provides console logging for all operations and support status
• Production: Logging is disabled via process.env.NODE_ENV checks