0
# Webpack LiveReload Plugin
1
2
A webpack plugin that enables live reload functionality during development by integrating with webpack's build pipeline. It automatically refreshes web pages when files change, offering an alternative to webpack-dev-server for cases where assets need to be served by an application server rather than webpack's dev server.
3
4
## Package Information
5
6
- **Package Name**: webpack-livereload-plugin
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install --save-dev webpack-livereload-plugin`
10
11
## Core Imports
12
13
```javascript
14
const LiveReloadPlugin = require('webpack-livereload-plugin');
15
```
16
17
For ES modules:
18
19
```javascript
20
import LiveReloadPlugin from 'webpack-livereload-plugin';
21
```
22
23
## Basic Usage
24
25
```javascript
26
// webpack.config.js
27
const LiveReloadPlugin = require('webpack-livereload-plugin');
28
29
module.exports = {
30
// webpack configuration
31
plugins: [
32
new LiveReloadPlugin({
33
port: 35729,
34
hostname: 'localhost'
35
})
36
]
37
};
38
```
39
40
Add the LiveReload script to your HTML:
41
42
```html
43
<script src="http://localhost:35729/livereload.js"></script>
44
```
45
46
## Architecture
47
48
The plugin integrates with webpack's plugin system using several key hooks:
49
50
- **Server Management**: Creates and manages a LiveReload server using the tiny-lr library
51
- **File Watching**: Hooks into webpack's compilation lifecycle to detect file changes
52
- **Change Detection**: Uses compilation hashes and optional source hashing to prevent unnecessary reloads
53
- **Script Injection**: Optionally injects LiveReload client script into webpack bundles
54
55
## Capabilities
56
57
### LiveReload Plugin Constructor
58
59
Creates a new LiveReload plugin instance with optional configuration.
60
61
```javascript { .api }
62
/**
63
* Creates a new LiveReload plugin instance
64
* @param {LiveReloadOptions} options - Configuration options
65
*/
66
function LiveReloadPlugin(options);
67
68
interface LiveReloadOptions {
69
/** Port for the LiveReload server (default: 35729, 0 for auto-find) */
70
port?: number;
71
/** RegExp or array of anymatch patterns for files to ignore */
72
ignore?: RegExp | Array<string | RegExp> | null;
73
/** Suppress console output (default: false) */
74
quiet?: boolean;
75
/** Use source hash to prevent unnecessary reloads (default: false) */
76
useSourceHash?: boolean;
77
/** Delay in milliseconds before triggering reload (default: 0) */
78
delay?: number;
79
/** Protocol for script tag URLs (default: detected from page) */
80
protocol?: string;
81
/** Hostname for script tag URLs (default: '" + location.hostname + "') */
82
hostname?: string;
83
/** Automatically append script tag to HTML (default: false) */
84
appendScriptTag?: boolean;
85
/** HTTPS key file content or path (passed to tiny-lr) */
86
key?: string;
87
/** HTTPS certificate file content or path (passed to tiny-lr) */
88
cert?: string;
89
/** HTTPS PFX file content or path (passed to tiny-lr) */
90
pfx?: string;
91
}
92
```
93
94
**Usage Examples:**
95
96
```javascript
97
// Basic setup
98
const plugin = new LiveReloadPlugin();
99
100
// Custom port and hostname
101
const plugin = new LiveReloadPlugin({
102
port: 1337,
103
hostname: '10.0.2.2'
104
});
105
106
// Ignore CSS files and use source hashing
107
const plugin = new LiveReloadPlugin({
108
ignore: /\.css$/,
109
useSourceHash: true,
110
delay: 20
111
});
112
113
// Multiple ignore patterns
114
const plugin = new LiveReloadPlugin({
115
ignore: [/\.map$/, /\.json$/]
116
});
117
118
// Auto-append script tag
119
const plugin = new LiveReloadPlugin({
120
appendScriptTag: true
121
});
122
123
// HTTPS setup
124
const plugin = new LiveReloadPlugin({
125
protocol: 'https',
126
key: fs.readFileSync('path/to/key.pem'),
127
cert: fs.readFileSync('path/to/cert.pem')
128
});
129
130
// Comprehensive example with multiple features
131
const plugin = new LiveReloadPlugin({
132
port: 0, // Auto-find available port
133
hostname: '192.168.1.100', // Custom hostname for network access
134
quiet: false, // Show server startup message
135
useSourceHash: true, // Prevent unnecessary reloads
136
delay: 100, // Small delay to batch rapid changes
137
ignore: [ // Ignore multiple file types
138
/\.map$/, // Source maps
139
/\.json$/, // JSON files
140
/node_modules/ // Dependencies
141
],
142
appendScriptTag: true // Auto-inject script into HTML
143
});
144
```
145
146
### Server Management
147
148
Controls the LiveReload server lifecycle.
149
150
```javascript { .api }
151
/**
152
* Start the LiveReload server
153
* @param {Object | null} watching - Webpack watching instance (unused)
154
* @param {Function} callback - Called when server starts or fails
155
*/
156
start(watching, callback);
157
158
/**
159
* Check if the LiveReload server is running
160
* @returns {boolean} True if server is running
161
*/
162
get isRunning();
163
```
164
165
### Compilation Integration
166
167
Handles webpack compilation events and change detection.
168
169
```javascript { .api }
170
/**
171
* Handle webpack compilation completion
172
* @param {Object} stats - Webpack compilation stats
173
*/
174
done(stats);
175
176
/**
177
* Handle webpack compilation failure
178
*/
179
failed();
180
181
/**
182
* Apply the plugin to webpack compiler (webpack plugin interface)
183
* @param {Object} compiler - Webpack compiler instance
184
*/
185
apply(compiler);
186
187
/**
188
* Hook into webpack compilation for script injection (internal method)
189
* @param {Object} compilation - Webpack compilation instance
190
*/
191
applyCompilation(compilation);
192
```
193
194
### Script Generation
195
196
Generates JavaScript code for LiveReload client integration.
197
198
```javascript { .api }
199
/**
200
* Generate JavaScript code for auto-loading LiveReload client
201
* @returns {string} JavaScript code to inject
202
*/
203
autoloadJs();
204
205
/**
206
* Optionally prepend LiveReload script to source code
207
* @param {string} source - Original JavaScript source
208
* @returns {string} Modified or original source
209
*/
210
scriptTag(source);
211
```
212
213
### Properties
214
215
Runtime properties accessible on plugin instances.
216
217
```javascript { .api }
218
interface LiveReloadPlugin {
219
/** Current port being used by the server */
220
port: number;
221
/** Default port used when no port is specified (35729) */
222
readonly defaultPort: number;
223
/** File ignore patterns */
224
ignore: RegExp | Array<string | RegExp> | null;
225
/** Whether console output is suppressed */
226
quiet: boolean;
227
/** Whether source hashing is enabled */
228
useSourceHash: boolean;
229
/** Reload delay in milliseconds */
230
delay: number;
231
/** Protocol string for script URLs */
232
protocol: string;
233
/** Hostname for script URLs (default: '" + location.hostname + "') */
234
hostname: string;
235
/** Whether the LiveReload server is running (getter) */
236
readonly isRunning: boolean;
237
/** Random hex string for unique instance identification */
238
readonly instanceId: string;
239
/** Last compilation hash for change detection (internal) */
240
readonly lastHash: string | null;
241
/** Array of last child compilation hashes (internal) */
242
readonly lastChildHashes: string[];
243
/** Storage for source file hashes when useSourceHash is enabled (internal) */
244
readonly sourceHashs: Record<string, string>;
245
/** Active tiny-lr server instance (internal) */
246
readonly server: TinyLRServer | null;
247
/** Webpack compiler instance (internal) */
248
readonly compiler: Object | null;
249
}
250
```
251
252
## Error Handling
253
254
The plugin handles common error scenarios:
255
256
- **Port conflicts**: Automatically searches for available ports when `port: 0`
257
- **Server errors**: Logs errors and continues operation when server fails to start
258
- **File filtering**: Safely handles invalid ignore patterns through anymatch library
259
260
**Common Error Messages:**
261
262
```javascript
263
// Port in use
264
"Live Reload disabled: EADDRINUSE"
265
266
// Server start failure
267
"Live Reload disabled: [error message]"
268
```
269
270
## Types
271
272
```javascript { .api }
273
interface WebpackCompilationStats {
274
compilation: {
275
/** Compilation hash for change detection */
276
hash: string;
277
/** Child compilation hashes */
278
children: Array<{ hash: string }>;
279
/** Compilation assets with emission status */
280
assets: {
281
[filename: string]: {
282
/** Whether the asset was emitted in this compilation */
283
emitted: boolean;
284
/** Function to get asset source (when useSourceHash is enabled) */
285
source?: () => string;
286
}
287
};
288
};
289
}
290
291
interface TinyLRServer {
292
/** Notify connected clients of file changes */
293
notifyClients(files: string[]): void;
294
/** Start listening on specified port */
295
listen(port: number, callback: (error?: Error) => void): void;
296
/** Close the server */
297
close(): void;
298
}
299
```