@capgo/capacitor-live-reload

WIP: Live reload your Capacitor app from a remote Vite (or compatible) dev server.

Note Configure your Vite dev server to disable the built-in HMR client and forward reload events (e.g. JSON payloads { "type": "full-reload" } or { "type": "file-update", "path": "..." }) over a dedicated WebSocket endpoint such as /capgo-livereload.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/live-reload/

Install

npm install @capgo/capacitor-live-reload
npx cap sync

import { LiveReload } from '@capgo/capacitor-live-reload';

await LiveReload.configureServer({
  url: 'http://localhost:5173',
  websocketPath: '/capgo-livereload',
});

await LiveReload.connect();

LiveReload.addListener('reloadEvent', (event) => {
  console.log('Live reload event', event);
});

API

• configureServer(...)
• connect()
• disconnect()
• getStatus()
• reload()
• reloadFile(...)
• addListener('reloadEvent', ...)
• addListener('statusChange', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases

configureServer(...)

configureServer(options: ConfigureServerOptions) => Promise<LiveReloadStatus>

Store remote dev server settings used for subsequent connections.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | ConfigureServerOptions |

Returns: Promise<LiveReloadStatus>

connect()

connect() => Promise<LiveReloadStatus>

Establish a WebSocket connection if one is not already active.

Returns: Promise<LiveReloadStatus>

disconnect()

disconnect() => Promise<LiveReloadStatus>

Close the current WebSocket connection and disable auto reconnect.

Returns: Promise<LiveReloadStatus>

getStatus()

getStatus() => Promise<LiveReloadStatus>

Returns the current connection status.

Returns: Promise<LiveReloadStatus>

reload()

reload() => Promise<void>

Trigger a full reload of the Capacitor WebView.

reloadFile(...)

reloadFile(options: FileUpdatePayload) => Promise<void>

Reload a single file/module if the runtime supports it (falls back to full reload).

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | FileUpdatePayload |

addListener('reloadEvent', ...)

addListener(eventName: 'reloadEvent', listenerFunc: LiveReloadEventCallback) => Promise<PluginListenerHandle>

Listen to incoming reload events emitted by the server.

| Param | Type | | ------------------ | --------------------------------------------------------------------------- | | eventName | 'reloadEvent' | | listenerFunc | LiveReloadEventCallback |

Returns: Promise<PluginListenerHandle>

addListener('statusChange', ...)

addListener(eventName: 'statusChange', listenerFunc: LiveReloadStatusCallback) => Promise<PluginListenerHandle>

Listen to socket status changes (connected/disconnected).

| Param | Type | | ------------------ | ----------------------------------------------------------------------------- | | eventName | 'statusChange' | | listenerFunc | LiveReloadStatusCallback |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners.

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version

Returns: Promise<{ version: string; }>

Interfaces

LiveReloadStatus

| Prop | Type | | --------------- | -------------------- | | connected | boolean | | url | string |

ConfigureServerOptions

| Prop | Type | Description | | ----------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | url | string | Base URL for the dev server (e.g. https://dev.local:5173). When a connection is established the Capacitor WebView navigates to this URL. | | websocketPath | string | Optional WebSocket path override when different from /ws. | | headers | Record<string, string> | Extra headers sent when creating the WebSocket connection. | | autoReconnect | boolean | Automatically reconnect when the socket closes unexpectedly. Default: true. | | reconnectInterval | number | Delay (ms) between reconnection attempts. Default: 2000. |

FileUpdatePayload

| Prop | Type | | ---------- | ------------------- | | path | string | | hash | string |

PluginListenerHandle

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

LiveReloadEventPayload

| Prop | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- | | type | LiveReloadMessageType | | | file | FileUpdatePayload | Populated when type === 'file-update'. | | message | string | Optional human-readable message for errors or status changes. |

Type Aliases

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

LiveReloadEventCallback

(event: LiveReloadEventPayload): void

LiveReloadMessageType

'full-reload' | 'file-update' | 'error' | 'connected' | 'disconnected'

LiveReloadStatusCallback

(status: LiveReloadStatus): void