0
# Server Operations
1

2
Core LiveReload server operations including WebSocket management, browser communication, and lifecycle control.
3

4
## Capabilities
5

6
### Server Creation
7

8
Creates a new LiveReload server instance with configuration options.
9

10
```javascript { .api }
11
/**
12
 * Creates a LiveReload server instance
13
 * @param config - Optional configuration object
14
 * @param callback - Optional callback executed when server starts listening
15
 * @returns Server instance extending EventEmitter
16
 */
17
function createServer(config = {}, callback) {
18
  // Internal implementation creates HTTP/HTTPS server and WebSocket server
19
  // Applies configuration defaults and validates options
20
  // Returns Server instance
21
}
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
const livereload = require('livereload');
28

29
// Basic server with defaults
30
const server = livereload.createServer();
31

32
// Server with custom port and debug
33
const server = livereload.createServer({
34
  port: 8080,
35
  debug: true
36
});
37

38
// Server with callback
39
const server = livereload.createServer({
40
  port: 35729
41
}, () => {
42
  console.log('LiveReload server is listening');
43
});
44

45
// HTTPS server
46
const fs = require('fs');
47
const server = livereload.createServer({
48
  https: {
49
    key: fs.readFileSync('server.key'),
50
    cert: fs.readFileSync('server.crt')
51
  }
52
});
53

54
// Server with CSS and image live reload
55
const server = livereload.createServer({
56
  applyCSSLive: true,   // Reload CSS without full page refresh (default: true) 
57
  applyImgLive: true    // Reload images without full page refresh (default: true)
58
});
59
```
60

61
### Server Listening
62

63
Starts the WebSocket server and begins accepting browser connections.
64

65
```javascript { .api }
66
/**
67
 * Start the WebSocket server and begin listening for connections
68
 * @param callback - Optional callback called when server starts listening
69
 */
70
listen(callback) {
71
  // Starts WebSocket server on configured port/host
72
  // Sets up connection, close, and error event handlers
73
  // Calls callback when ready to accept connections
74
}
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
const server = livereload.createServer({ noListen: true });
81

82
// Start listening manually
83
server.listen(() => {
84
  console.log('Server is now listening for connections');
85
});
86

87
// Start listening without callback
88
server.listen();
89
```
90

91
### File Watching
92

93
Monitors file system paths for changes and triggers browser reloads.
94

95
```javascript { .api }
96
/**
97
 * Start watching file system paths for changes
98
 * @param paths - File path(s) or glob patterns to watch
99
 */
100
watch(paths) {
101
  // Uses chokidar to monitor file system changes
102
  // Applies configured exclusions and extensions filtering
103
  // Triggers refresh() when relevant files change
104
}
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
// Watch single directory
111
server.watch(__dirname + '/public');
112

113
// Watch multiple directories
114
server.watch([
115
  __dirname + '/public',
116
  __dirname + '/assets'
117
]);
118

119
// Watch specific files with glob patterns
120
server.watch([
121
  './src/**/*.js',
122
  './styles/**/*.css'
123
]);
124
```
125

126
### Browser Refresh
127

128
Sends reload commands to all connected browsers.
129

130
```javascript { .api }
131
/**
132
 * Send reload command to all connected browsers
133
 * @param filepath - Path of the changed file
134
 */
135
refresh(filepath) {
136
  // Constructs reload message with file path and configuration
137
  // Sends WebSocket message to all connected clients
138
  // Applies CSS live reload settings if applicable
139
}
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
// Manually trigger a refresh
146
server.refresh('/path/to/changed/file.css');
147

148
// Refresh is typically called automatically by file watcher
149
// But can be triggered programmatically when needed
150
```
151

152
### Browser Alerts
153

154
Sends alert messages to all connected browsers.
155

156
```javascript { .api }
157
/**
158
 * Send alert message to all connected browsers
159
 * @param message - Alert message to display
160
 */
161
alert(message) {
162
  // Sends alert command via WebSocket to all connected clients
163
  // Message appears as browser alert dialog
164
}
165
```
166

167
**Usage Examples:**
168

169
```javascript
170
// Send alert to browsers
171
server.alert('Build completed successfully!');
172
server.alert('Compilation error in main.js');
173
```
174

175
### Server Shutdown
176

177
Closes file watchers and shuts down the WebSocket server.
178

179
```javascript { .api }
180
/**
181
 * Stop file watching and close WebSocket server
182
 */
183
close() {
184
  // Closes chokidar file watcher if active
185
  // Shuts down WebSocket server and underlying HTTP server
186
  // Cleanup of all resources and connections
187
}
188
```
189

190
**Usage Examples:**
191

192
```javascript
193
// Graceful shutdown
194
process.on('SIGINT', () => {
195
  console.log('Shutting down LiveReload server...');
196
  server.close();
197
  process.exit(0);
198
});
199

200
// Close server programmatically
201
server.close();
202
```
203

204
### Event Handling
205

206
The Server extends EventEmitter and emits events for error handling.
207

208
```javascript { .api }
209
/**
210
 * Server events
211
 */
212

213
// Error event - emitted when server encounters errors
214
server.on('error', (err) => {
215
  // Handle server errors (port in use, WebSocket errors, etc.)
216
});
217
```
218

219
**Usage Examples:**
220

221
```javascript
222
const server = livereload.createServer();
223

224
// Handle server errors
225
server.on('error', (err) => {
226
  if (err.code === 'EADDRINUSE') {
227
    console.log('Port is already in use');
228
    process.exit(1);
229
  } else {
230
    console.error('LiveReload server error:', err);
231
  }
232
});
233

234
server.watch('./public');
235
```
236

237
## WebSocket Protocol Details
238

239
### Client Handshake
240

241
The server handles WebSocket protocol handshake automatically:
242

243
- **hello command**: Client initiates handshake, server responds with protocol information
244
- **info command**: Client sends capability information, server acknowledges
245

246
### Server Messages
247

248
The server sends these message types to browsers:
249

250
- **reload**: Instructs browser to reload page or specific resource
251
- **alert**: Displays alert message in browser
252

253
## Integration Patterns
254

255
### Express/Connect Integration
256

257
```javascript
258
const express = require('express');
259
const livereload = require('livereload');
260

261
const app = express();
262
const server = livereload.createServer();
263

264
app.use(express.static('public'));
265
app.listen(3000);
266

267
// Watch the public directory
268
server.watch(__dirname + '/public');
269
```
270

271
### Build Tool Integration
272

273
```javascript
274
const livereload = require('livereload');
275

276
// Create server with delay for build processes
277
const server = livereload.createServer({
278
  delay: 1000,  // Wait 1 second after file change
279
  debug: true
280
});
281

282
// Watch source and output directories
283
server.watch(['./src', './dist']);
284

285
// Manual refresh after build completion
286
function onBuildComplete() {
287
  server.refresh('./dist/bundle.js');
288
}
289
```