@capgo/capacitor-webview-guardian

Keep your Capacitor app alive after the OS kills its WebView while the app is in the background. Webview Guardian listens for foreground events, probes the renderer, and reloads it automatically (or notifies you so you can recover your own state) when the render process was terminated.

Install

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

Usage

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

await WebviewGuardian.startMonitoring({
  foregroundDebounceMs: 800,
  autoRestart: true,
  restartStrategy: 'reload',
});

WebviewGuardian.addListener('webviewRestarted', ({ reason }) => {
  console.info('[guardian] WebView restarted', reason);
});

API

• startMonitoring(...)
• stopMonitoring()
• getState()
• checkNow(...)
• addListener('foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', ...)
• Interfaces
• Type Aliases

startMonitoring(...)

startMonitoring(options?: StartMonitoringOptions | undefined) => Promise<GuardianState>

Starts observing foreground events and automatically checks the WebView health.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | StartMonitoringOptions |

Returns: Promise<GuardianState>

stopMonitoring()

stopMonitoring() => Promise<GuardianState>

Stops any automatic foreground monitoring.

Returns: Promise<GuardianState>

getState()

getState() => Promise<GuardianState>

Returns the latest known monitoring state.

Returns: Promise<GuardianState>

checkNow(...)

checkNow(options?: CheckNowOptions | undefined) => Promise<CheckResult>

Forces a WebView health probe immediately.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | CheckNowOptions |

Returns: Promise<CheckResult>

addListener('foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', ...)

addListener(eventName: 'foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', listenerFunc: (event: GuardianEvent) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | eventName | 'foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted' | | listenerFunc | (event: GuardianState) => void |

Returns: Promise<PluginListenerHandle>

Interfaces

GuardianState

| Prop | Type | | -------------------------- | -------------------- | | monitoring | boolean | | reason | string | | timestamp | string | | lastHealthyAt | string | | lastRestartAt | string | | lastCrashAt | string | | pendingRestartReason | string | | error | string |

StartMonitoringOptions

| Prop | Type | Description | | -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | foregroundDebounceMs | number | Delay (in ms) before running a health check after the app re-enters the foreground. Defaults to 600ms to let the bridge finish resuming. | | pingScript | string | Script executed via evaluateJavascript/evaluateJavaScript to confirm the WebView is alive. Defaults to document.readyState. | | autoRestart | boolean | Automatically reloads the WebView when a terminated render process is detected. Disable to receive webviewCrashed events and restart manually. | | restartStrategy | RestartStrategy | Strategy used when restarting the WebView. Defaults to reload. | | customRestartUrl | string | Custom HTTPS/HTTP URL to load when restartStrategy is customUrl. | | debug | boolean | Emits verbose logging in the native layer when true. | | runInitialCheck | boolean | Whether an immediate health check should be executed right after enabling monitoring. Defaults to true. |

CheckResult

| Prop | Type | | -------------------- | -------------------- | | healthy | boolean | | restarted | boolean | | reason | string | | timestamp | string | | error | string | | pendingRestart | boolean |

CheckNowOptions

| Prop | Type | Description | | ------------ | ------------------- | ---------------------------------------------------------- | | reason | string | Text tag describing why a manual check is being requested. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Type Aliases

RestartStrategy

'reload' | 'reloadFromOrigin' | 'customUrl'

GuardianEvent

GuardianState