0
# Watchify
1

2
Watchify is a development tool that provides watch mode functionality for browserify builds, enabling automatic recompilation of JavaScript bundles when source files change. It offers both command-line and programmatic APIs with features like configurable delay timing, file watching patterns, and detailed verbose output showing build times and file sizes.
3

4
## Package Information
5

6
- **Package Name**: watchify
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g watchify` (global CLI) or `npm install watchify` (library)
10

11
## Core Imports
12

13
```javascript
14
var watchify = require('watchify');
15
```
16

17
## Basic Usage
18

19
### Command Line Interface
20

21
```bash
22
# Basic usage with required output file
23
watchify main.js -o static/bundle.js
24

25
# With verbose output showing build stats
26
watchify main.js -o static/bundle.js -v
27

28
# With custom delay and ignore patterns
29
watchify main.js -o bundle.js --delay 200 --ignore-watch "**/node_modules/**"
30
```
31

32
### Programmatic API
33

34
```javascript
35
var browserify = require('browserify');
36
var watchify = require('watchify');
37
var fs = require('fs');
38

39
// Create browserify instance with required cache options
40
var b = browserify({
41
  entries: ['src/main.js'],
42
  cache: {},
43
  packageCache: {},
44
  plugin: [watchify]
45
});
46

47
// Handle file changes
48
b.on('update', bundle);
49
bundle();
50

51
function bundle() {
52
  b.bundle()
53
    .on('error', console.error)
54
    .pipe(fs.createWriteStream('bundle.js'));
55
}
56
```
57

58
## Capabilities
59

60
### Main Watchify Function
61

62
Creates a watching browserify instance that automatically rebuilds when source files change.
63

64
```javascript { .api }
65
/**
66
 * Creates a watching browserify instance that auto-rebuilds on file changes
67
 * @param {Object} b - browserify instance (required)
68
 * @param {Object} opts - options object (optional)
69
 * @returns {Object} Enhanced browserify instance with watching capabilities
70
 */
71
function watchify(b, opts);
72
```
73

74
**Options:**
75

76
```javascript { .api }
77
interface WatchifyOptions {
78
  /** Wait time in milliseconds before emitting 'update' event after file changes */
79
  delay?: number; // default: 100
80
  
81
  /** File patterns to ignore when watching. If true, defaults to '**/node_modules/**' */
82
  ignoreWatch?: string | string[] | boolean | Function;
83
  
84
  /** Enable polling mode. If true, uses 100ms interval. If number, uses that as interval */
85
  poll?: boolean | number;
86
}
87
```
88

89
### Default Arguments Object
90

91
Pre-configured browserify arguments for optimal caching.
92

93
```javascript { .api }
94
/**
95
 * Default browserify arguments with cache and packageCache
96
 */
97
watchify.args = {
98
  cache: {},
99
  packageCache: {}
100
};
101
```
102

103
### Enhanced Browserify Instance Methods
104

105
When you pass a browserify instance to watchify, it gains additional methods:
106

107
```javascript { .api }
108
/**
109
 * Close all file watchers
110
 * @returns {undefined}
111
 */
112
b.close();
113

114
/**
115
 * Internal watcher creation method (advanced usage)
116
 * @param {string} file - File path to watch
117
 * @param {Object} opts - Chokidar watcher options
118
 * @returns {Object} Chokidar watcher instance
119
 */
120
b._watcher(file, opts);
121
```
122

123
## Events
124

125
The enhanced browserify instance emits additional events for monitoring build process:
126

127
### File Change Events
128

129
```javascript { .api }
130
/**
131
 * Emitted when files change
132
 * @param {string[]} ids - Array of changed file IDs
133
 */
134
b.on('update', function(ids) {
135
  // Rebuild bundle when files change
136
});
137
```
138

139
### Build Metrics Events
140

141
```javascript { .api }
142
/**
143
 * Emitted with number of bytes in generated bundle
144
 * @param {number} bytes - Bundle size in bytes
145
 */
146
b.on('bytes', function(bytes) {
147
  console.log('Bundle size:', bytes, 'bytes');
148
});
149

150
/**
151
 * Emitted with time taken to build bundle
152
 * @param {number} time - Build time in milliseconds
153
 */
154
b.on('time', function(time) {
155
  console.log('Build time:', time, 'ms');
156
});
157

158
/**
159
 * Emitted with formatted log message about build stats
160
 * @param {string} msg - Formatted message with bytes and time
161
 */
162
b.on('log', function(msg) {
163
  console.log(msg); // "X bytes written (Y seconds)"
164
});
165
```
166

167
## Command Line Interface
168

169
### Required Options
170

171
```bash { .api }
172
# Required: specify output file
173
--outfile=FILE, -o FILE
174
```
175

176
### Standard Options
177

178
```bash { .api }
179
# Show verbose build information
180
--verbose, -v
181

182
# Display version information
183
--version
184
```
185

186
### Advanced Options
187

188
```bash { .api }
189
# Wait time before emitting update event (default: 100ms)
190
--delay=MILLISECONDS
191

192
# Ignore file patterns when watching (default: false)
193
--ignore-watch=GLOB, --iw GLOB
194

195
# Use polling instead of native file watching (default: false)
196
--poll=INTERVAL
197
```
198

199
## Usage Examples
200

201
### Basic File Watching
202

203
```javascript
204
var browserify = require('browserify');
205
var watchify = require('watchify');
206

207
var b = browserify({
208
  entries: ['app.js'],
209
  cache: {},
210
  packageCache: {}
211
});
212

213
var w = watchify(b);
214

215
w.on('update', function(ids) {
216
  console.log('Files changed:', ids);
217
  bundle();
218
});
219

220
function bundle() {
221
  w.bundle()
222
    .pipe(process.stdout);
223
}
224

225
bundle(); // Initial build
226
```
227

228
### Advanced Configuration
229

230
```javascript
231
var browserify = require('browserify');
232
var watchify = require('watchify');
233

234
var b = browserify({
235
  entries: ['src/main.js'],
236
  cache: {},
237
  packageCache: {}
238
});
239

240
var w = watchify(b, {
241
  delay: 200,
242
  ignoreWatch: ['**/node_modules/**', '**/test/**'],
243
  poll: 1000 // Use 1 second polling
244
});
245

246
w.on('update', rebuild);
247
w.on('bytes', function(bytes) {
248
  console.log('Bundle:', bytes, 'bytes');
249
});
250
w.on('time', function(time) {
251
  console.log('Built in:', time, 'ms');
252
});
253

254
function rebuild() {
255
  w.bundle()
256
    .on('error', function(err) {
257
      console.error('Build error:', err.message);
258
    })
259
    .pipe(require('fs').createWriteStream('dist/bundle.js'));
260
}
261

262
rebuild(); // Initial build
263
```
264

265
### Integration with Transforms
266

267
For custom browserify transforms that add files to the bundle:
268

269
```javascript
270
// In your transform
271
module.exports = function(file) {
272
  return through(function(buf, enc, next) {
273
    // Inform watchify about additional files to watch
274
    this.emit('file', '/absolute/path/to/dependency.js');
275
    next();
276
  });
277
};
278
```
279

280
### Error Handling
281

282
```javascript
283
var b = browserify({ cache: {}, packageCache: {} });
284
var w = watchify(b);
285

286
w.on('update', bundle);
287

288
function bundle() {
289
  var stream = w.bundle();
290
  
291
  stream.on('error', function(err) {
292
    console.error('Browserify error:', err.message);
293
  });
294
  
295
  stream.pipe(require('fs').createWriteStream('output.js'));
296
}
297

298
bundle();
299
```
300

301
## Important Notes
302

303
1. **Cache Requirements**: You MUST set `cache: {}` and `packageCache: {}` properties when creating the browserify instance
304
2. **Initial Bundle**: Watchify will not emit 'update' events until you've called `b.bundle()` once and completely drained the stream
305
3. **Output File Required**: When using the CLI, the `-o` or `--outfile` option is mandatory
306
4. **Shell Commands**: The output file can be a shell command (not available on Windows) using pipes and redirects
307
5. **Cleanup**: Call `b.close()` to close all file watchers when done
308
6. **Error Handling**: Add error listeners to bundle streams to ensure errors are properly reported
309

310
## Browser Compatibility
311

312
Watchify is a Node.js development tool and is not intended to run in browsers. It's used during development to watch and rebuild browserify bundles that will eventually run in browsers.