@capgo/capacitor-webview-guardian

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

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