@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/

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8.*.*	v8.*.*	✅
v7.*.*	v7.*.*	On demand
v6.*.*	v6.*.*	❌
v5.*.*	v5.*.*	❌

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

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