@capgo/capacitor-live-reload

➡️ Get Instant updates for your App with Capgo

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

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