0
# File Watching
1

2
File system monitoring capabilities with configurable extensions, exclusion patterns, and polling options for network file systems.
3

4
## Capabilities
5

6
### Default File Extensions
7

8
LiveReload watches specific file extensions by default.
9

10
```javascript { .api }
11
/**
12
 * Default file extensions that trigger browser reload
13
 */
14
const DEFAULT_EXTENSIONS = [
15
  'html', 'css', 'js', 'png', 'gif', 'jpg',
16
  'php', 'php5', 'py', 'rb', 'erb', 'coffee'
17
];
18
```
19

20
### Live Reload Behavior
21

22
LiveReload has different reload behaviors for different file types:
23

24
- **CSS files**: When `applyCSSLive` is true (default), CSS files are reloaded without a full page refresh
25
- **Image files**: When `applyImgLive` is true (default), image files (jpg, jpeg, png, gif) are reloaded without a full page refresh  
26
- **Other files**: All other file types trigger a full page refresh
27

28
```javascript { .api }
29
/**
30
 * Configure live reload behavior for CSS and images
31
 */
32
const server = livereload.createServer({
33
  applyCSSLive: true,   // CSS live reload (default: true)
34
  applyImgLive: true    // Image live reload (default: true)
35
});
36
```
37

38
### Default Exclusions
39

40
Certain directories are excluded from watching by default.
41

42
```javascript { .api }
43
/**
44
 * Default regex patterns for excluded directories
45
 */
46
const DEFAULT_EXCLUSIONS = [
47
  /\.git\//,    // Git repository files
48
  /\.svn\//,    // Subversion files  
49
  /\.hg\//      // Mercurial files
50
];
51
```
52

53
### Extension Configuration
54

55
Control which file types trigger browser reloads.
56

57
```javascript { .api }
58
/**
59
 * Configure file extensions to watch
60
 */
61

62
// Replace default extensions entirely
63
const server = livereload.createServer({
64
  exts: ['html', 'css', 'js']  // Only watch these types
65
});
66

67
// Add additional extensions to defaults  
68
const server = livereload.createServer({
69
  extraExts: ['scss', 'less', 'tsx']  // Adds to default list
70
});
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
const livereload = require('livereload');
77

78
// Watch only HTML and CSS files
79
const server = livereload.createServer({
80
  exts: ['html', 'css']
81
});
82

83
// Watch default extensions plus additional ones
84
const server = livereload.createServer({
85
  extraExts: ['md', 'txt', 'json']
86
});
87

88
// Note: extraExts overrides exts if both are provided
89
const server = livereload.createServer({
90
  exts: ['html'],           // This gets ignored
91
  extraExts: ['scss', 'js'] // Results in: scss, js + defaults
92
});
93
```
94

95
### Exclusion Patterns
96

97
Configure which files and directories to ignore.
98

99
```javascript { .api }
100
/**
101
 * Configure exclusion patterns
102
 * @param exclusions - Array of RegExp patterns to exclude
103
 */
104
const server = livereload.createServer({
105
  exclusions: [
106
    /node_modules\//,
107
    /\.tmp$/,
108
    /\.log$/
109
  ]
110
});
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
// Exclude specific directories and file types
117
const server = livereload.createServer({
118
  exclusions: [
119
    /node_modules\//,
120
    /dist\//,
121
    /build\//,
122
    /\.backup$/,
123
    /~$/
124
  ]
125
});
126

127
// Exclusions are appended to defaults, not replaced
128
// So .git/, .svn/, .hg/ are always excluded
129
```
130

131
### Specific File Monitoring
132

133
Watch specific filenames regardless of extension.
134

135
```javascript { .api }
136
/**
137
 * Configure specific filenames that trigger reload
138
 * @param filesToReload - Array of filenames to watch
139
 */
140
const server = livereload.createServer({
141
  filesToReload: ['index.html', 'config.json', 'Makefile']
142
});
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
// Watch specific files by name
149
const server = livereload.createServer({
150
  filesToReload: [
151
    'index.html',    // Any index.html in any directory
152
    'config.js',     // Any config.js file  
153
    'Dockerfile'     // Dockerfiles (no extension)
154
  ]
155
});
156

157
// Useful for files without extensions or special files
158
const server = livereload.createServer({
159
  exts: ['js'],
160
  filesToReload: ['Makefile', 'README', '.env']
161
});
162
```
163

164
### Polling Mode
165

166
Use polling instead of file system events for network drives.
167

168
```javascript { .api }
169
/**
170
 * Enable polling for file system changes
171
 * @param usePolling - Set to true for network file systems
172
 */
173
const server = livereload.createServer({
174
  usePolling: true
175
});
176
```
177

178
**Usage Examples:**
179

180
```javascript
181
// For network drives or Docker volumes
182
const server = livereload.createServer({
183
  usePolling: true,
184
  debug: true  // See polling activity in logs
185
});
186

187
// Polling is more resource intensive but works reliably
188
// across different file systems and network mounts
189
```
190

191
### Watch Multiple Paths
192

193
Monitor multiple directories or glob patterns.
194

195
```javascript { .api }
196
/**
197
 * Watch multiple paths simultaneously
198
 * @param paths - String or array of paths/patterns to watch
199
 */
200
server.watch(paths);
201
```
202

203
**Usage Examples:**
204

205
```javascript
206
const server = livereload.createServer();
207

208
// Watch multiple specific directories
209
server.watch([
210
  __dirname + '/public',
211
  __dirname + '/assets',
212
  __dirname + '/templates'
213
]);
214

215
// Watch with glob patterns
216
server.watch([
217
  './src/**/*.js',
218
  './styles/**/*.css',
219
  './public/**/*.html'
220
]);
221

222
// Mix of directories and patterns
223
server.watch([
224
  './public',           // Entire directory
225
  './src/**/*.js',      // JS files in src tree
226
  './config.json'       // Specific file
227
]);
228
```
229

230
### Delay Configuration
231

232
Add delay between file change detection and browser notification.
233

234
```javascript { .api }
235
/**
236
 * Configure delay before notifying browser
237
 * @param delay - Milliseconds to wait after file change
238
 */
239
const server = livereload.createServer({
240
  delay: 1000  // Wait 1 second
241
});
242
```
243

244
**Usage Examples:**
245

246
```javascript
247
// Useful for build processes that take time
248
const server = livereload.createServer({
249
  delay: 2000,  // Wait 2 seconds after change
250
  debug: true
251
});
252

253
// Prevents premature reloads during compilation
254
server.watch('./src');
255

256
// Without delay, browser might reload before
257
// build process completes the file changes
258
```
259

260
## File Change Detection
261

262
### Internal Filter Logic
263

264
LiveReload uses internal logic to determine if a file change should trigger a reload:
265

266
1. **Extension Check**: File extension must be in the `exts` array
267
2. **Filename Check**: Filename must be in the `filesToReload` array  
268
3. **Exclusion Check**: File path must not match any exclusion patterns
269
4. **Delay Processing**: If delay is configured, waits before triggering
270

271
### File System Events
272

273
Uses chokidar internally to monitor these events:
274

275
- **add**: New file created
276
- **change**: Existing file modified  
277
- **unlink**: File deleted
278

279
All three events can trigger browser reloads depending on configuration.
280

281
## Advanced Configuration
282

283
### Combining Options
284

285
```javascript
286
// Comprehensive file watching configuration
287
const server = livereload.createServer({
288
  // Watch TypeScript and SCSS in addition to defaults
289
  extraExts: ['ts', 'tsx', 'scss'],
290
  
291
  // Exclude build artifacts and temp files
292
  exclusions: [
293
    /node_modules\//,
294
    /\.tmp$/,
295
    /build\//,
296
    /dist\//
297
  ],
298
  
299
  // Watch config files specifically
300
  filesToReload: ['webpack.config.js', 'package.json'],
301
  
302
  // Use polling for Docker/VM environments
303
  usePolling: process.env.NODE_ENV === 'docker',
304
  
305
  // Delay for build processes
306
  delay: 500,
307
  
308
  // Debug file watching
309
  debug: true
310
});
311

312
server.watch('./src');
313
```
314

315
### Network File Systems
316

317
```javascript
318
// Optimized for network drives and containers
319
const server = livereload.createServer({
320
  usePolling: true,
321
  debug: true,
322
  delay: 1000  // Higher delay for network latency
323
});
324
```
325

326
### Development vs Production
327

328
```javascript
329
// Different configs for different environments
330
const isDev = process.env.NODE_ENV === 'development';
331

332
const server = livereload.createServer({
333
  debug: isDev,
334
  usePolling: process.platform === 'win32' || isDev,
335
  delay: isDev ? 0 : 1000,
336
  extraExts: isDev ? ['scss', 'ts'] : []
337
});
338
```