Getting Started

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-webview-crash`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/webview-crash/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Install

bun add @capgo/capacitor-webview-crash
bunx cap sync

Import

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

Recommended recovery flow

Attach the listener 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();
});

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

API overview

`getPendingCrashInfo`

Returns the stored native crash 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 crash 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);

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.
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 metadata, or `null` when no marker is pending.
   */
  value: WebViewCrashInfo | null;
}

`WebViewCrashInfo`

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

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

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

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

  /**
   * Last known WebView URL when the crash 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' | '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.