CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-offline-plugin

A webpack plugin for offline-first web applications using ServiceWorker and AppCache

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

runtime-api.mddocs/

Runtime API

The runtime API provides client-side functions for managing offline functionality, handling cache updates, and responding to connectivity changes.

Core Functions

install

function install(options?: InstallOptions): void;

Installs and initializes the ServiceWorker or AppCache for offline functionality. This function must be called each time your application loads - it's safe to call repeatedly.

Parameters:

  • options (optional): Configuration object with event handlers

Usage:

// Basic installation
require('offline-plugin/runtime').install();

// ES6/TypeScript
import * as OfflinePluginRuntime from 'offline-plugin/runtime';
OfflinePluginRuntime.install();

applyUpdate

function applyUpdate(): void;

Applies a pending cache update. Typically called from the onUpdateReady event handler to activate new cached content.

Usage:

require('offline-plugin/runtime').install({
  onUpdateReady: () => {
    require('offline-plugin/runtime').applyUpdate();
  }
});

update

function update(): void;

Manually triggers a check for cache updates. The update process will fire appropriate events based on the result.

Usage:

// Check for updates on user action
document.getElementById('update-btn').addEventListener('click', () => {
  require('offline-plugin/runtime').update();
});

Event Handling

InstallOptions Interface

interface InstallOptions {
  onInstalled?: () => void;
  onUpdating?: () => void;
  onUpdateReady?: () => void;
  onUpdateFailed?: () => void;
  onUpdated?: () => void;
}

Event handlers for managing the offline functionality lifecycle.

onInstalled

onInstalled?: () => void;

Called exactly once when the ServiceWorker or AppCache is successfully installed and ready. Ideal for displaying "App ready for offline use" messages.

Usage:

install({
  onInstalled: () => {
    console.log('App is ready for offline usage');
    showNotification('Ready for offline use!');
  }
});

onUpdating

onUpdating?: () => void;

Called when an update is found and the download process begins. Not supported for AppCache. Use this to show loading indicators.

Usage:

install({
  onUpdating: () => {
    console.log('Downloading updates...');
    showSpinner('Updating app...');
  }
});

onUpdateReady

onUpdateReady?: () => void;

Called when the update download is complete and ready to be applied. All new assets are downloaded and cached. Call applyUpdate() to activate the new version.

Usage:

install({
  onUpdateReady: () => {
    console.log('Update ready - applying...');
    // Immediately apply the update
    require('offline-plugin/runtime').applyUpdate();
  }
});

onUpdateFailed

onUpdateFailed?: () => void;

Called when the update process fails. No new content was downloaded. The current cached version remains active.

Usage:

install({
  onUpdateFailed: () => {
    console.warn('Update failed - continuing with current version');
    hideSpinner();
  }
});

onUpdated

onUpdated?: () => void;

Called when the update has been successfully applied, either through applyUpdate() or automatically by the browser. The new version is now active.

Usage:

install({
  onUpdated: () => {
    console.log('App updated successfully');
    // Reload to use the new version
    window.location.reload();
  }
});

Complete Usage Examples

Basic Update Handling

require('offline-plugin/runtime').install({
  onInstalled: () => {
    console.log('SW Event:', 'onInstalled');
  },
  
  onUpdateReady: () => {
    console.log('SW Event:', 'onUpdateReady');
    // Automatically apply update
    require('offline-plugin/runtime').applyUpdate();
  },
  
  onUpdated: () => {
    console.log('SW Event:', 'onUpdated');
    // Reload page to use new version
    window.location.reload();
  }
});

User-Controlled Updates

let updateAvailable = false;

require('offline-plugin/runtime').install({
  onUpdateReady: () => {
    updateAvailable = true;
    showUpdatePrompt('A new version is available. Update now?');
  },
  
  onUpdated: () => {
    window.location.reload();
  }
});

function applyPendingUpdate() {
  if (updateAvailable) {
    require('offline-plugin/runtime').applyUpdate();
  }
}

Advanced Update Management

const runtime = require('offline-plugin/runtime');

// Track update state
let isUpdating = false;

runtime.install({
  onInstalled: () => {
    setStatus('Ready for offline use');
  },
  
  onUpdating: () => {
    isUpdating = true;
    setStatus('Downloading update...', true);
  },
  
  onUpdateReady: () => {
    isUpdating = false;
    setStatus('Update ready');
    
    // Ask user before applying
    if (confirm('Update available. Apply now?')) {
      runtime.applyUpdate();
    }
  },
  
  onUpdateFailed: () => {
    isUpdating = false;
    setStatus('Update failed', false);
  },
  
  onUpdated: () => {
    setStatus('Updated successfully');
    setTimeout(() => window.location.reload(), 1000);
  }
});

// Check for updates periodically
setInterval(() => {
  if (!isUpdating) {
    runtime.update();
  }
}, 5 * 60 * 1000); // Every 5 minutes

TypeScript Usage

import * as OfflinePluginRuntime from 'offline-plugin/runtime';

interface UpdateState {
  isInstalled: boolean;
  isUpdating: boolean;
  hasUpdate: boolean;
}

const state: UpdateState = {
  isInstalled: false,
  isUpdating: false,
  hasUpdate: false
};

OfflinePluginRuntime.install({
  onInstalled: (): void => {
    state.isInstalled = true;
    console.log('ServiceWorker installed');
  },
  
  onUpdating: (): void => {
    state.isUpdating = true;
  },
  
  onUpdateReady: (): void => {
    state.isUpdating = false;
    state.hasUpdate = true;
    
    // Auto-apply in production, prompt in development
    if (process.env.NODE_ENV === 'production') {
      OfflinePluginRuntime.applyUpdate();
    } else {
      console.log('Update ready - call applyUpdate() to apply');
    }
  },
  
  onUpdated: (): void => {
    state.hasUpdate = false;
    window.location.reload();
  }
});

Install with Tessl CLI

npx tessl i tessl/npm-offline-plugin

docs

index.md

plugin-configuration.md

runtime-api.md

tile.json