{"id":15295,"library":"aedes-server-factory","title":"Aedes Server Factory","description":"aedes-server-factory is a utility library designed to simplify the creation and configuration of various server types for the Aedes MQTT broker. It currently supports TCP, HTTP, HTTP2, WebSockets (WS), and PROXY decoders, with ongoing work for TLS, HTTPS, and WSS. The latest stable version is 0.2.1, with releases happening infrequently, often driven by bug fixes or minor feature enhancements related to server handling. Its primary differentiator is providing a consolidated API to instantiate and bind Aedes to different network protocols and server technologies, abstracting away the boilerplate involved in connecting an MQTT broker to diverse client interfaces. It offers flexible options for secure connections and proxy support.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/moscajs/aedes-server-factory","tags":["javascript","mqtt","proxy","server","http","tcp","ws","typescript"],"install":[{"cmd":"npm install aedes-server-factory","lang":"bash","label":"npm"},{"cmd":"yarn add aedes-server-factory","lang":"bash","label":"yarn"},{"cmd":"pnpm add aedes-server-factory","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core MQTT broker to which the factory binds connections.","package":"aedes","optional":false},{"reason":"Required for WebSocket server functionality.","package":"ws","optional":true}],"imports":[{"note":"While CommonJS `require` still works for Node.js, `import` is preferred for modern TypeScript/ESM projects.","wrong":"const { createServer } = require('aedes-server-factory');","symbol":"createServer","correct":"import { createServer } from 'aedes-server-factory';"},{"note":"Aedes is a default export, not a named export.","wrong":"import { Aedes } from 'aedes';","symbol":"Aedes","correct":"import Aedes from 'aedes';"}],"quickstart":{"code":"import Aedes from 'aedes';\nimport { createServer } from 'aedes-server-factory';\nimport { createServer as createHttpServer } from 'http';\n\nconst aedes = Aedes();\n\n// Create a basic TCP MQTT server\nconst tcpServer = createServer(aedes);\ntcpServer.listen(1883, () => {\n  console.log('Aedes TCP server listening on port 1883');\n});\n\n// Create an HTTP server and bind it for WebSockets\nconst httpServer = createHttpServer();\nconst wsServer = createServer(aedes, { ws: true, http: httpServer });\n\nhttpServer.listen(8080, () => {\n  console.log('Aedes HTTP/WS server listening on port 8080');\n});\n\n// Handle cleanup on process exit\nprocess.on('SIGTERM', () => {\n  console.log('Shutting down Aedes servers...');\n  tcpServer.close(() => console.log('TCP server closed.'));\n  wsServer.close(() => console.log('HTTP/WS server closed.'));\n  aedes.close(() => console.log('Aedes broker closed.'));\n});","lang":"typescript","description":"Demonstrates creating both a default TCP MQTT server and a WebSocket server using an underlying HTTP server with aedes-server-factory."},"warnings":[{"fix":"Review your WebSocket error handling. The `customWSErrorHandler` option can be used to provide specific error management. Monitor for new releases addressing this comprehensively.","message":"Version 0.2.0 included a fix for an infinite loop issue (#8) which was subsequently reverted in 0.2.0 itself (#10) due to unintended side effects. Users who relied on the fix in interim builds might find the behavior reverted, and should carefully test error handling, especially for WS servers.","severity":"breaking","affected_versions":"0.2.0"},{"fix":"Ensure you are interacting with the correct server instance returned by `createServer`. For WebSocket setups, the returned object is the HTTP server providing the WebSocket upgrade path.","message":"When using `ws: true`, `createServer` returns the underlying HTTP/HTTP2/HTTPS server instance, not the WebSocket server directly. Methods like `.close()` should be called on this returned instance.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly test TLS/HTTPS/HTTP2/WSS configurations in non-production environments. Check the latest GitHub issues and pull requests for status updates and potential workarounds or recommended alternative approaches for production deployments.","message":"TLS/HTTPS/HTTP2/WSS support is marked as 'Work In Progress' in the README. While options exist, they might not be fully stable or production-ready as of version 0.2.1.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `aedes` is correctly initialized via `const aedes = require('aedes')()` or `import Aedes from 'aedes'; const aedes = Aedes();` before passing it to `createServer`.","cause":"Attempting to call `aedes.handle` directly on an object that is not a proper Aedes instance or has not been correctly initialized.","error":"TypeError: aedes.handle is not a function"},{"fix":"Change the port number to an available one, or identify and terminate the process currently occupying the port (e.g., `lsof -i :1883` on macOS/Linux or `netstat -ano | findstr :1883` on Windows).","cause":"Another process is already using the specified port, preventing the server from starting.","error":"Error: listen EADDRINUSE: address already in use :::1883"},{"fix":"Verify that `ws: true` is correctly passed in the options to `createServer` and that the `ws` package is installed (`npm install ws`). Also, check your client-side WebSocket URL and protocol for correctness.","cause":"The underlying HTTP server is running, but the WebSocket upgrade request failed, possibly because `ws: true` was not set, or there's an issue with the `ws` package.","error":"Error: WebSocket connection to 'ws://localhost:8080/' failed: Error during WebSocket handshake: Unexpected response code: 400"}],"ecosystem":"npm"}