0
# Configuration
1

2
Configuration system for customizing LiveReload behavior, connection settings, and reloading strategies. Options can be specified either as a global object or as URL query parameters in the script tag.
3

4
## Capabilities
5

6
### Global Configuration Object
7

8
Set configuration using a global `LiveReloadOptions` object before the LiveReload script loads.
9

10
```javascript { .api }
11
/**
12
 * Global configuration object for LiveReload
13
 * Must be defined before livereload.js script loads
14
 */
15
window.LiveReloadOptions = {
16
  host?: string,
17
  port?: number | string,
18
  https?: boolean,
19
  path?: string,
20
  mindelay?: number,
21
  maxdelay?: number,
22
  handshake_timeout?: number,
23
  isChromeExtension?: boolean,
24
  reloadMissingCSS?: boolean,
25
  pluginOrder?: string[],
26
  ext?: string,
27
  extver?: string,
28
  snipver?: string
29
};
30
```
31

32
**Usage Examples:**
33

34
```html
35
<script>
36
    // Configure LiveReload before script loads
37
    window.LiveReloadOptions = {
38
        host: 'dev.example.com',
39
        port: 8080,
40
        mindelay: 500,
41
        maxdelay: 30000,
42
        reloadMissingCSS: false
43
    };
44
</script>
45
<script src="http://dev.example.com:8080/livereload.js"></script>
46
```
47

48
### URL Query Parameters
49

50
Configure LiveReload using query parameters in the script tag URL.
51

52
```html { .api }
53
<!-- Configure via script tag URL parameters -->
54
<script src="http://localhost:35729/livereload.js?host=custom&port=8080&mindelay=500"></script>
55
```
56

57
**Usage Examples:**
58

59
```html
60
<!-- Basic configuration -->
61
<script src="http://localhost:35729/livereload.js?snipver=1"></script>
62

63
<!-- Custom host and timing -->
64
<script src="https://example.com/livereload.js?host=localhost&port=3000&mindelay=2000&maxdelay=120000"></script>
65

66
<!-- Plugin order configuration -->
67
<script src="http://localhost:35729/livereload.js?pluginOrder=css,img,external"></script>
68
```
69

70
### Connection Options
71

72
Configure the connection to the LiveReload server.
73

74
```javascript { .api }
75
interface ConnectionOptions {
76
  /** LiveReload server hostname (required if using LiveReloadOptions) */
77
  host: string;
78
  
79
  /** Server port number or empty string to inherit from page */
80
  port: number | string;
81
  
82
  /** Use HTTPS/WSS connection instead of HTTP/WS */
83
  https: boolean;
84
  
85
  /** Server path for WebSocket connection (default: 'livereload') */
86
  path: string;
87
  
88
  /** Extension name for protocol handshake (optional) */
89
  ext: string;
90
  
91
  /** Extension version for protocol handshake (optional) */
92
  extver: string;
93
  
94
  /** Snippet version for compatibility checking (optional) */
95
  snipver: string;
96
}
97
```
98

99
**Usage Examples:**
100

101
```javascript
102
// Standard local development
103
window.LiveReloadOptions = {
104
    host: 'localhost',
105
    port: 35729
106
};
107

108
// Custom server setup
109
window.LiveReloadOptions = {
110
    host: 'dev.mycompany.com',
111
    port: 8080,
112
    https: true,
113
    path: 'custom-livereload'
114
};
115

116
// Inherit port from current page (useful with proxies)
117
window.LiveReloadOptions = {
118
    host: location.hostname,
119
    port: ''  // Empty string inherits port
120
};
121
```
122

123
### Timing Options
124

125
Configure reconnection timing and timeout behavior.
126

127
```javascript { .api }
128
interface TimingOptions {
129
  /** Minimum delay between reconnection attempts in milliseconds (default: 1000) */
130
  mindelay: number;
131
  
132
  /** Maximum delay between reconnection attempts in milliseconds (default: 60000) */
133
  maxdelay: number;
134
  
135
  /** Timeout for protocol handshake completion in milliseconds (default: 5000) */
136
  handshake_timeout: number;
137
}
138
```
139

140
**Usage Examples:**
141

142
```javascript
143
// Fast reconnection for stable networks
144
window.LiveReloadOptions = {
145
    mindelay: 500,
146
    maxdelay: 10000,
147
    handshake_timeout: 2000
148
};
149

150
// Conservative timing for unstable networks
151
window.LiveReloadOptions = {
152
    mindelay: 5000,
153
    maxdelay: 300000,  // 5 minutes
154
    handshake_timeout: 15000
155
};
156
```
157

158
### Behavior Options
159

160
Configure how LiveReload handles different types of reloading operations.
161

162
```javascript { .api }
163
interface BehaviorOptions {
164
  /** Reload Chrome extension runtime instead of page (default: false) */
165
  isChromeExtension: boolean;
166
  
167
  /** Prevent CSS reload when changed stylesheet isn't found (default: true) */
168
  reloadMissingCSS: boolean;
169
  
170
  /** Override default plugin execution order */
171
  pluginOrder: string[];
172
}
173
```
174

175
**Usage Examples:**
176

177
```javascript
178
// Chrome extension development
179
window.LiveReloadOptions = {
180
    isChromeExtension: true
181
};
182

183
// Strict CSS reloading - only reload if stylesheet is found
184
window.LiveReloadOptions = {
185
    reloadMissingCSS: false
186
};
187

188
// Custom plugin execution order
189
window.LiveReloadOptions = {
190
    pluginOrder: ['css', 'img']  // Only CSS and image reloading
191
};
192
```
193

194
### Plugin Order Configuration
195

196
Control the order and selection of reload strategies.
197

198
```javascript { .api }
199
/**
200
 * Plugin order values:
201
 * - 'external': Run all external plugins in default order
202
 * - 'css': Live CSS reloading without page refresh
203
 * - 'img': Live image reloading
204
 * - 'extension': Chrome extension runtime reloading  
205
 * - 'others': Full page reload fallback
206
 * - Custom plugin identifiers: Run specific plugins by ID
207
 */
208
type PluginOrderValue = 'external' | 'css' | 'img' | 'extension' | 'others' | string;
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
// Only CSS and image reloading, no page refresh
215
window.LiveReloadOptions = {
216
    pluginOrder: ['css', 'img']
217
};
218

219
// CSS first, then external plugins, then fallback
220
window.LiveReloadOptions = {
221
    pluginOrder: ['css', 'external', 'others']
222
};
223

224
// Specific plugin order with custom plugins
225
window.LiveReloadOptions = {
226
    pluginOrder: ['less', 'css', 'my-custom', 'img']
227
};
228
```
229

230
### Debug Configuration
231

232
Enable verbose logging for debugging LiveReload behavior.
233

234
```html { .api }
235
<!-- Enable verbose logging via URL parameter -->
236
<script src="http://localhost:35729/livereload.js?LR-verbose"></script>
237
```
238

239
**Usage Examples:**
240

241
```html
242
<!-- Debug mode with configuration -->
243
<script src="http://localhost:35729/livereload.js?host=localhost&port=3000&LR-verbose"></script>
244

245
<!-- Debug mode with snippet version -->
246
<script src="http://localhost:35729/livereload.js?snipver=1&LR-verbose"></script>
247
```
248

249
### Browserify Configuration
250

251
Special configuration when using LiveReload with Browserify.
252

253
```javascript { .api }
254
/**
255
 * Required configuration for Browserify usage
256
 * Must specify host since script tag cannot be auto-detected
257
 */
258
window.LiveReloadOptions = { host: 'localhost' };
259
require('livereload-js');
260
```
261

262
**Usage Examples:**
263

264
```javascript
265
// Basic Browserify setup
266
window.LiveReloadOptions = { host: 'localhost' };
267
require('livereload-js');
268

269
// Advanced Browserify configuration
270
window.LiveReloadOptions = {
271
    host: 'localhost',
272
    port: 3000,
273
    mindelay: 1000,
274
    pluginOrder: ['css', 'external', 'others']
275
};
276
require('livereload-js');
277
```