0
# LiveReload
1

2
LiveReload is a Node.js implementation of the LiveReload server that monitors files for changes and automatically reloads web browsers. It serves as a command-line alternative to the graphical LiveReload application, offering both CLI and programmatic API interfaces for integration into development workflows.
3

4
## Package Information
5

6
- **Package Name**: livereload
7
- **Package Type**: npm
8
- **Language**: JavaScript (compiled from CoffeeScript)
9
- **Installation**: `npm install livereload` or `npm install -g livereload` for CLI usage
10

11
## Core Imports
12

13
```javascript
14
const livereload = require('livereload');
15
```
16

17
ES Module:
18
```javascript
19
import { createServer } from 'livereload';
20
```
21

22
For CLI usage:
23
```javascript
24
const { run, createServerFromArgs } = require('livereload/lib/command');
25
```
26

27
## Basic Usage
28

29
```javascript
30
const livereload = require('livereload');
31

32
// Create and start a LiveReload server
33
const server = livereload.createServer();
34
server.watch(__dirname + "/public");
35

36
// Server will monitor files and reload browsers automatically
37
```
38

39
## Architecture
40

41
LiveReload is built around several key components:
42

43
- **Server Class**: Core WebSocket server that handles browser connections and file change notifications
44
- **File Watcher**: Uses chokidar for efficient file system monitoring with configurable patterns
45
- **WebSocket Protocol**: Implements LiveReload protocol v7 for browser communication
46
- **HTTP Server**: Serves the client-side livereload.js script and handles CORS/CORP headers
47
- **CLI Interface**: Command-line wrapper with extensive configuration options
48

49
## Capabilities
50

51
### Server Creation and Configuration
52

53
Creates a LiveReload server instance with extensive configuration options for ports, file watching patterns, CORS settings, and browser behavior.
54

55
```javascript { .api }
56
function createServer(config?: ServerConfig, callback?: () => void): Server;
57

58
interface ServerConfig {
59
  // Network configuration
60
  port?: number;              // Default: 35729
61
  host?: string;              // Default: 'localhost'
62
  https?: object;             // HTTPS server options
63
  server?: object;            // Custom HTTP/HTTPS server
64

65
  // File watching configuration
66
  exts?: string[];            // File extensions to watch (replaces defaults)
67
  extraExts?: string[];       // Additional extensions (appends to defaults)
68
  exclusions?: RegExp[];      // Regex patterns to exclude
69
  filesToReload?: string[];   // Specific filenames that trigger reload
70
  usePolling?: boolean;       // Use polling instead of file events
71

72
  // Browser behavior
73
  applyCSSLive?: boolean;     // Reload CSS without page refresh (default: true)
74
  applyImgLive?: boolean;     // Reload images without page refresh (default: true)
75
  originalPath?: string;      // URL to proxy for development
76
  overrideURL?: string;       // Different host for CSS files
77
  delay?: number;             // Delay in milliseconds before notifying browser
78

79
  // CORS/Security
80
  cors?: boolean | string;    // Enable CORS support
81
  corp?: boolean;             // Enable Cross-Origin Resource Policy
82

83
  // Control options
84
  debug?: boolean;            // Show debug messages
85
  noListen?: boolean;         // Don't start WebSocket server automatically
86
  version?: string;           // Protocol version (default: '7')
87
}
88
```
89

90
[Server Operations](./server-operations.md)
91

92
### File System Monitoring
93

94
File watching capabilities with configurable extensions, exclusion patterns, and polling options for network file systems.
95

96
```javascript { .api }
97
// Default extensions watched
98
const DEFAULT_EXTENSIONS = [
99
  'html', 'css', 'js', 'png', 'gif', 'jpg', 
100
  'php', 'php5', 'py', 'rb', 'erb', 'coffee'
101
];
102

103
// Default exclusion patterns
104
const DEFAULT_EXCLUSIONS = [/\.git\//, /\.svn\//, /\.hg\//];
105
```
106

107
[File Watching](./file-watching.md)
108

109
### Command Line Interface
110

111
Complete CLI with option parsing for all server configuration options plus path specification and help text.
112

113
```javascript { .api }
114
function run(): void; // Main CLI entry point
115

116
function createServerFromArgs(testArgv: string[]): {
117
  server: Server;
118
  path: string | string[];
119
}; // Parse CLI args and create server (for testing)
120
```
121

122
[Command Line Interface](./cli.md)
123

124
## Types
125

126
```javascript { .api }
127
interface Server extends EventEmitter {
128
  config: ServerConfig;
129
  
130
  listen(callback?: () => void): void;
131
  watch(paths: string | string[]): void;
132
  refresh(filepath: string): void;
133
  alert(message: string): void;
134
  close(): void;
135
  debug(str: string): void;  // Internal debug logging method
136
}
137

138
// Protocol version and default constants
139
const PROTOCOL_VERSION = '7';
140
const DEFAULT_PORT = 35729;
141
const DEFAULT_HOST = 'localhost';
142

143
interface ServerConfig {
144
  port: number;
145
  host: string;
146
  version: string;
147
  exts: string[];
148
  extraExts: string[];
149
  exclusions: RegExp[];
150
  filesToReload: string[];
151
  applyCSSLive: boolean;
152
  applyImgLive: boolean;
153
  originalPath: string;
154
  overrideURL: string;
155
  usePolling: boolean;
156
  delay?: number;
157
  debug?: boolean;
158
  cors?: boolean | string;
159
  corp?: boolean;
160
  https?: object;
161
  server?: object;
162
  noListen?: boolean;
163
}
164
```