0
# Client API
1

2
Core LiveReload client functionality including connection management, event handling, and plugin registration. The LiveReload client is automatically instantiated when the script loads and provides the main interface for interacting with the LiveReload system.
3

4
## Capabilities
5

6
### Global LiveReload Instance
7

8
The main LiveReload client instance is automatically created and exposed globally when the script loads.
9

10
```javascript { .api }
11
/**
12
 * Global LiveReload client instance
13
 * Available as window.LiveReload after script loads
14
 */
15
const LiveReload = window.LiveReload;
16
```
17

18
**Usage Examples:**
19

20
```javascript
21
// Check if LiveReload is available
22
if (window.LiveReload) {
23
    console.log('LiveReload is active');
24
    
25
    // Register event handlers
26
    LiveReload.on('connect', () => {
27
        console.log('Connected to LiveReload server');
28
    });
29
}
30
```
31

32
### Event Registration
33

34
Register event handlers for LiveReload lifecycle events.
35

36
```javascript { .api }
37
/**
38
 * Register an event handler for LiveReload events
39
 * @param eventName - Event name: 'connect', 'disconnect', or 'shutdown'
40
 * @param handler - Function to call when event occurs
41
 */
42
LiveReload.on(eventName, handler);
43
```
44

45
**Supported Events:**
46
- `'connect'`: Fired when connection to LiveReload server is established
47
- `'disconnect'`: Fired when connection to LiveReload server is lost
48
- `'shutdown'`: Fired when LiveReload is shutting down
49

50
**Usage Examples:**
51

52
```javascript
53
// Connection established
54
LiveReload.on('connect', () => {
55
    console.log('LiveReload connected');
56
    showStatusIndicator('connected');
57
});
58

59
// Connection lost
60
LiveReload.on('disconnect', () => {
61
    console.log('LiveReload disconnected');
62
    showStatusIndicator('disconnected');
63
});
64

65
// LiveReload shutting down
66
LiveReload.on('shutdown', () => {
67
    console.log('LiveReload shut down');
68
    cleanupResources();
69
});
70
```
71

72
### Manual Shutdown
73

74
Manually disconnect from the LiveReload server and shut down the client.
75

76
```javascript { .api }
77
/**
78
 * Disconnect from LiveReload server and shut down the client
79
 * Triggers the 'shutdown' event and cleans up resources
80
 */
81
LiveReload.shutDown();
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
// Shut down LiveReload when user clicks button
88
document.getElementById('disable-livereload').addEventListener('click', () => {
89
    LiveReload.shutDown();
90
    console.log('LiveReload disabled by user');
91
});
92

93
// Conditional shutdown based on environment
94
if (window.location.hostname === 'production.example.com') {
95
    LiveReload.shutDown();
96
}
97
```
98

99
### Plugin Management
100

101
Register and check for plugins that extend LiveReload functionality.
102

103
```javascript { .api }
104
/**
105
 * Register a plugin class with the LiveReload client
106
 * @param PluginClass - Plugin constructor function with static identifier and version
107
 */
108
LiveReload.addPlugin(PluginClass);
109

110
/**
111
 * Check if a plugin with the given identifier is registered
112
 * @param identifier - Plugin identifier string
113
 * @returns True if plugin is registered, false otherwise
114
 */
115
LiveReload.hasPlugin(identifier);
116
```
117

118
**Usage Examples:**
119

120
```javascript
121
// Check if LESS plugin is available
122
if (LiveReload.hasPlugin('less')) {
123
    console.log('LESS plugin is active');
124
}
125

126
// Register a custom plugin
127
class MyCustomPlugin {
128
    static identifier = 'my-custom';
129
    static version = '1.0.0';
130
    
131
    constructor(window, host) {
132
        this.window = window;
133
        this.host = host;
134
    }
135
    
136
    reload(path, options) {
137
        if (path.endsWith('.custom')) {
138
            // Handle custom file reloading
139
            this.host.console.log('Reloading custom file:', path);
140
            return true;
141
        }
142
        return false;
143
    }
144
}
145

146
LiveReload.addPlugin(MyCustomPlugin);
147
```
148

149
### Console Logging
150

151
LiveReload provides console logging that respects debug settings.
152

153
```javascript { .api }
154
/**
155
 * Log a message through LiveReload's console system
156
 * Respects LR-verbose URL parameter for debug output
157
 * @param message - Message to log
158
 */
159
LiveReload.log(message);
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
// Log custom messages
166
LiveReload.log('Custom reload operation completed');
167

168
// Debug information (only shown with ?LR-verbose)
169
if (window.location.href.includes('LR-verbose')) {
170
    LiveReload.log('Debug: Processing file changes');
171
}
172
```
173

174
### Plugin Analysis
175

176
Trigger analysis of all registered plugins and send information to the LiveReload server.
177

178
```javascript { .api }
179
/**
180
 * Analyze all registered plugins and send data to server
181
 * Automatically called when connection is established
182
 * Only works with protocol version 7 or higher
183
 */
184
LiveReload.analyze();
185
```
186

187
**Usage Examples:**
188

189
```javascript
190
// Manually trigger analysis (usually not needed)
191
if (LiveReload && typeof LiveReload.analyze === 'function') {
192
    LiveReload.analyze();
193
    console.log('Plugin analysis sent to server');
194
}
195

196
// Check if analysis is supported (protocol version 7+)
197
LiveReload.on('connect', () => {
198
    if (LiveReload._connector && LiveReload._connector.protocol >= 7) {
199
        console.log('Plugin analysis supported');
200
    }
201
});
202
```