{"id":12651,"library":"watchify-middleware","title":"Watchify Middleware","description":"watchify-middleware is a lightweight HTTP middleware designed to enhance the development experience when working with Watchify and Browserify. It prevents stale or empty bundles from being served by suspending the server response until the bundle is ready. The middleware, currently at version 1.9.1 (last published in 2017), differentiates itself by removing the default 600ms rebuild delay common in Watchify, offering immediate feedback, and providing an optional browser-based error handler. It exposes timing information via a 'log' event and facilitates seamless integration into Node.js HTTP servers or frameworks like Express, making it ideal for rapid iteration cycles during web development. Its release cadence has been infrequent, with no major updates since its last stable release, positioning it as a mature, maintenance-mode utility.","status":"maintenance","version":"1.9.1","language":"javascript","source_language":"en","source_url":"git://github.com/mattdesl/watchify-middleware","tags":["javascript","watchify","server","fast","reload","incremental","suspend","request","response"],"install":[{"cmd":"npm install watchify-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add watchify-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add watchify-middleware","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import watchifyMiddleware from 'watchify-middleware'","symbol":"watchifyMiddleware","correct":"const watchifyMiddleware = require('watchify-middleware')"},{"note":"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.","wrong":"import { emitter } from 'watchify-middleware'","symbol":"watchifyMiddleware.emitter","correct":"const emitter = watchifyMiddleware.emitter(bundler, opt)"},{"note":"The primary export is a function that returns another function (the middleware itself), not a class constructor. Do not use `new`.","wrong":"const middleware = new watchifyMiddleware(bundler)","symbol":"middleware","correct":"const middleware = watchifyMiddleware(bundler)"}],"quickstart":{"code":"const http = require('http');\nconst browserify = require('browserify');\nconst watchifyMiddleware = require('watchify-middleware');\nconst defaultIndex = require('simple-html-index');\n\nconst staticUrl = 'bundle.js';\nconst appEntry = 'app.js';\n\n// Create a dummy app.js for demonstration\nrequire('fs').writeFileSync(appEntry, 'console.log(\"Hello from app.js!\");');\n\nconst bundler = browserify(appEntry, {\n  cache: {},\n  packageCache: {},\n  basedir: __dirname,\n  plugin: [require('watchify')] // Crucial for watchify integration\n});\n\nconst watchifyInstance = watchifyMiddleware(bundler, {\n  errorHandler: true // Use default browser error handler\n});\n\nconst server = http.createServer(function (req, res) {\n  if (req.url === '/') {\n    defaultIndex({ entry: staticUrl }).pipe(res);\n  } else if (req.url === '/' + staticUrl) {\n    watchifyInstance(req, res);\n  } else {\n    res.writeHead(404, { 'Content-Type': 'text/plain' });\n    res.end('Not Found');\n  }\n});\n\nserver.listen(8000, 'localhost', function () {\n  console.log('Watching and serving http://localhost:8000/');\n  console.log(`Try changing ${appEntry} and refreshing the browser.`);\n});","lang":"javascript","description":"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."},"warnings":[{"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 })`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When creating your Browserify instance, always include `{ cache: {}, packageCache: {}, plugin: [require('watchify')] }` in its options, along with `basedir` for proper resolution.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Browserify bundler cannot locate the entry point file specified.","error":"Error: Cannot find module 'app.js'"},{"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.","cause":"The server attempted to listen on a port that is already occupied by another process.","error":"Error: listen EADDRINUSE: address already in use :::8000"},{"fix":"Ensure your `browserify` configuration includes `{ cache: {}, packageCache: {}, plugin: [require('watchify')] }`.","cause":"The Browserify instance is likely missing the `cache`, `packageCache` options, or the `watchify` plugin, preventing incremental builds.","error":"Bundle is not updating in the browser after file changes, or updates are very slow."},{"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.","cause":"This is often expected behavior if `watchify` is currently rebuilding the bundle. The middleware suspends the response until the bundle is ready.","error":"My server is hanging or not responding when I request the bundle URL."}],"ecosystem":"npm"}