Getting Started

Install

npm install @capgo/capacitor-webview-crash
npx cap sync

Import

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

Recommended recovery flow

Attach listeners as early as possible in your app startup so the recovered runtime can react before users continue navigating:

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

await WebViewCrash.addListener('webViewRestoredAfterCrash', async (info) => {
  console.log('Recovered after a WebView crash', info);

  // Rehydrate critical state, reopen the correct screen, or prompt the user to retry.
  await WebViewCrash.clearPendingCrashInfo();
});

await WebViewCrash.addListener('webViewRestoredAfterRestart', async (info) => {
  console.log('Recovered after a native WebView restart', info);
  await WebViewCrash.clearPendingCrashInfo();
});

const pending = await WebViewCrash.getPendingCrashInfo();
// Note: the listener callback may have already cleared the pending marker.
if (pending.value) {
  console.log('Pending crash or restart marker', pending.value);
}

Native auto restart

Set restart options in capacitor.config.ts so the decision stays in native code even when the JavaScript runtime has crashed or has not loaded yet:

import type { CapacitorConfig } from '@capacitor/cli';
import type { WebViewCrashPluginConfig } from '@capgo/capacitor-webview-crash';

const webViewCrash: WebViewCrashPluginConfig = {
  // Enabled by default. Keep this on for long-running apps.
  restartOnCrash: true,

  // Use a 5-field cron schedule in the device local timezone.
  // Do not combine restartCron with an active restartIntervalMs.
  restartCron: '0 3 * * *',

  // Optional delay before restarting after a crash.
  restartAfterCrashDelayMs: 0,
};

const config: CapacitorConfig = {
  plugins: {
    WebViewCrash: webViewCrash,
  },
};

export default config;

Use restartIntervalMs for always-on apps where users may keep the same WebView open for days: kiosk screens, control-room dashboards, warehouse scanners, POS terminals, fleet tablets, and digital signage. Use restartCron for wall-clock restarts such as 0 3 * * * for a daily 03:00 restart in the device local timezone. Scheduled restarts write a pending marker with reason: 'periodicRestart', then Android recreates the host activity and iOS rebuilds the Capacitor bridge view so a new WKWebView is created from native code.

Choose an interval or cron schedule your product can tolerate. restartCron supports *, lists, ranges, and steps. Do not configure both schedules at once: native initialization throws a fatal config error when restartCron is set and restartIntervalMs is greater than 0. A restart creates a fresh JavaScript runtime, so persist queued events, unsaved form state, and current navigation state before using aggressive schedules.

Manual native restart

Call restartWebView() when the current JavaScript runtime decides the native WebView should be replaced proactively, for example after a memory-heavy workflow or before entering a long unattended session:

await WebViewCrash.restartWebView();

The method writes a pending marker with reason: 'manualRestart', resolves the current call, then asks native code to create a fresh WebView. Android recreates the host activity. iOS rebuilds the Capacitor bridge view so a new WKWebView is created instead of reloading the current page.

API overview

getPendingCrashInfo

Returns the stored native crash or restart marker, or null when nothing is pending.

const pending = await WebViewCrash.getPendingCrashInfo();
if (pending.value) {
  console.log(pending.value.platform, pending.value.reason);
}

clearPendingCrashInfo

Clears the stored marker after your recovery handling is finished.

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

Creates a fake crash marker so QA and local debugging can exercise the recovery path without crashing a real WebView.

const simulated = await WebViewCrash.simulateCrashRecovery();
console.log(simulated.value);

restartWebView

Stores a manual restart marker and asks native code to create a fresh WebView.

await WebViewCrash.restartWebView();

Platform notes

• Android stores crash metadata from onRenderProcessGone, including didCrash and rendererPriorityAtExit when the platform provides them.
• iOS stores crash metadata from webViewWebContentProcessDidTerminate and adds the current application state when available.
• Manual and scheduled restarts create a fresh WebView. Android recreates the host activity; iOS rebuilds the Capacitor bridge view.
• Scheduled restarts use reason: 'periodicRestart'; manual restarts use reason: 'manualRestart'.
• Web does not detect real renderer crashes. The web implementation only simulates the behavior with local storage.

Type reference

PendingCrashInfoResult

export interface PendingCrashInfoResult {
  /**
   * Stored crash or restart metadata, or `null` when no marker is pending.
   */
  value: WebViewCrashInfo | null;
}

WebViewCrashPluginConfig

export interface WebViewCrashPluginConfig {
  /**
   * Restart the WebView from native code when the renderer process dies.
   *
   * @default true
   */
  restartOnCrash?: boolean;

  /**
   * Fixed native interval, in milliseconds, for proactively replacing long-running WebViews.
   *
   * Set to `0` to disable interval restarts. Do not combine an active interval
   * with `restartCron`; native initialization fails fast when both schedules are configured.
   *
   * @default 0
   */
  restartIntervalMs?: number;

  /**
   * Cron schedule for proactively replacing long-running WebViews.
   *
   * Uses standard 5-field cron syntax in the device local timezone:
   * `minute hour day-of-month month day-of-week`.
   *
   * Examples:
   * - `0 3 * * *` restarts every day at 03:00.
   * - `0,30 * * * *` restarts every 30 minutes.
   *
   * Do not combine this with an active `restartIntervalMs`; native initialization
   * fails fast when both schedules are configured.
   */
  restartCron?: string;

  /**
   * Delay, in milliseconds, before restarting after a crash.
   *
   * @default 0
   */
  restartAfterCrashDelayMs?: number;
}

WebViewCrashInfo

export interface WebViewCrashInfo {
  /**
   * Platform that detected and stored the marker.
   */
  platform: WebViewCrashPlatform;

  /**
   * Unix timestamp in milliseconds for when the marker was written.
   */
  timestamp: number;

  /**
   * ISO-8601 version of `timestamp`.
   */
  timestampISO: string;

  /**
   * Platform-specific reason for the crash or restart marker.
   */
  reason: WebViewCrashReason;

  /**
   * Last known WebView URL when the marker was written.
   */
  url?: string;

  /**
   * Android-only hint from `RenderProcessGoneDetail.didCrash()`.
   */
  didCrash?: boolean;

  /**
   * Android-only renderer priority reported at exit.
   */
  rendererPriorityAtExit?: number;

  /**
   * iOS-only application state captured when the WebView process died.
   */
  appState?: WebViewCrashAppState;
}

WebViewCrashPlatform

export type WebViewCrashPlatform = 'android' | 'ios' | 'web';

WebViewCrashReason

export type WebViewCrashReason =
  | 'renderProcessGone'
  | 'webContentProcessDidTerminate'
  | 'periodicRestart'
  | 'manualRestart'
  | 'simulated';

WebViewCrashAppState

export type WebViewCrashAppState = 'active' | 'inactive' | 'background' | 'unknown';

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Keep going from Getting Started

If you are using Getting Started to plan native media and interface behavior, connect it with Using @capgo/capacitor-webview-crash for the native capability in Using @capgo/capacitor-webview-crash, Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities for the implementation detail in @capgo/capacitor-live-activities, Using @capgo/capacitor-video-player for the native capability in Using @capgo/capacitor-video-player, and @capgo/capacitor-video-player for the implementation detail in @capgo/capacitor-video-player.