Watchify Middleware

Common errors

• Error: Cannot find module 'app.js'

  cause The Browserify bundler cannot locate the entry point file specified.
  fix Ensure that the `app.js` (or your entry file) exists at the path relative to `basedir` provided to Browserify, or specify the full absolute path.

• Error: listen EADDRINUSE: address already in use :::8000

  cause The server attempted to listen on a port that is already occupied by another process.
  fix Either stop the process currently using port 8000 (e.g., kill any lingering Node.js processes) or configure your server to listen on a different, available port.

• Bundle is not updating in the browser after file changes, or updates are very slow.

  cause The Browserify instance is likely missing the `cache`, `packageCache` options, or the `watchify` plugin, preventing incremental builds.
  fix Ensure your `browserify` configuration includes `{ cache: {}, packageCache: {}, plugin: [require('watchify')] }`.

• My server is hanging or not responding when I request the bundle URL.

  cause This is often expected behavior if `watchify` is currently rebuilding the bundle. The middleware suspends the response until the bundle is ready.
  fix Check the server console for 'log' events from watchify-middleware, indicating if a rebuild is in progress. If the server hangs indefinitely, ensure there are no errors in your `browserify` setup or your application code that are preventing a successful bundle completion.

Warnings

• breaking watchify-middleware explicitly removes the default 600ms debounce delay often present in standard Watchify setups. This means rebuilds will occur immediately upon file changes, which can be a change in behavior if you were relying on that delay.
  Fix: If a delay is desired (e.g., for large projects or frequent, rapid file changes), reintroduce it via the `delay` option: `watchifyMiddleware(bundler, { delay: 600 })`.
• gotcha The `errorHandler` option significantly alters how bundle errors are handled. If `errorHandler` is `true` (defaulting to a browser-console error display) or a custom function, the 'error' event on the emitter will *not* be triggered. Errors will be handled internally by the middleware or your custom function.
  Fix: To receive 'error' events, ensure `errorHandler` is `false`. If using a custom `errorHandler` function, handle logging or side effects within that function. Be mindful that using `errorHandler: true` will inject client-side `console.error` calls into your bundle.
• gotcha For watchify-middleware to function correctly and efficiently with incremental rebuilds, the underlying Browserify instance *must* be configured with `cache: {}`, `packageCache: {}`, and the `watchify` plugin. Omitting these will result in full rebuilds on every change, negating the performance benefits.
  Fix: When creating your Browserify instance, always include `{ cache: {}, packageCache: {}, plugin: [require('watchify')] }` in its options, along with `basedir` for proper resolution.
• gotcha watchify-middleware suspends the HTTP response until a fresh bundle is ready. While this prevents serving stale bundles, it means that requests for the bundle URL will appear to 'hang' or take longer during active rebuilds, which might be unexpected behavior for some server monitoring tools or developers.
  Fix: This is intended behavior. Communicate this characteristic to developers. Ensure your client-side code is robust enough to handle potentially longer response times for the bundle. The 'log' events can be used to monitor rebuild status on the server.

Install

• npm install watchify-middleware npm
• yarn add watchify-middleware yarn
• pnpm add watchify-middleware pnpm

Imports

• watchifyMiddleware
  wrong:

  import watchifyMiddleware from 'watchify-middleware'

  correct:

  const watchifyMiddleware = require('watchify-middleware')

  This package is primarily designed for CommonJS environments due to its age and Node.js server context. Direct ESM `import` might require bundler configuration or be incompatible with older Node.js versions.
• watchifyMiddleware.emitter
  wrong:

  import { emitter } from 'watchify-middleware'

  correct:

  const emitter = watchifyMiddleware.emitter(bundler, opt)

  The `emitter` API is exposed as a static method on the main `require()`d object, providing an event-driven interface for monitoring bundle updates and logs instead of directly handling requests and responses.
• middleware
  wrong:

  const middleware = new watchifyMiddleware(bundler)

  correct:

  const middleware = watchifyMiddleware(bundler)

  The primary export is a function that returns another function (the middleware itself), not a class constructor. Do not use `new`.

Quickstart

This quickstart sets up a basic HTTP server that serves an HTML page with a 'bundle.js' script. The script is generated by Browserify and hot-reloaded by watchify-middleware, demonstrating how to integrate the middleware to serve continuously updated JavaScript bundles.

const http = require('http');
const browserify = require('browserify');
const watchifyMiddleware = require('watchify-middleware');
const defaultIndex = require('simple-html-index');

const staticUrl = 'bundle.js';
const appEntry = 'app.js';

// Create a dummy app.js for demonstration
require('fs').writeFileSync(appEntry, 'console.log("Hello from app.js!");');

const bundler = browserify(appEntry, {
  cache: {},
  packageCache: {},
  basedir: __dirname,
  plugin: [require('watchify')] // Crucial for watchify integration
});

const watchifyInstance = watchifyMiddleware(bundler, {
  errorHandler: true // Use default browser error handler
});

const server = http.createServer(function (req, res) {
  if (req.url === '/') {
    defaultIndex({ entry: staticUrl }).pipe(res);
  } else if (req.url === '/' + staticUrl) {
    watchifyInstance(req, res);
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('Not Found');
  }
});

server.listen(8000, 'localhost', function () {
  console.log('Watching and serving http://localhost:8000/');
  console.log(`Try changing ${appEntry} and refreshing the browser.`);
});