bonjour: Zeroconf/mDNS Service Discovery

Common errors

• Error: bind EADDRINUSE 0.0.0.0:5353

  cause Another process on the system is already using UDP port 5353, which is the standard mDNS port `bonjour` attempts to bind to.
  fix Ensure no other Bonjour/mDNS service (or another instance of your application) is running. On some systems, restarting the machine can resolve this. You can also pass custom `port` options to the `multicast-dns` server when initializing `bonjour` if necessary, though this might hinder interoperability.

• Service not found or 'up' event never fires.

  cause This typically indicates a network issue (firewall, router blocking multicast, client/server on different subnets) or an incorrect service `type` being searched for versus what is being published.
  fix Double-check that both the publishing and browsing applications are on the same local network segment and are using identical service `type` strings. Temporarily disable firewalls for testing. Use network debugging tools (like Wireshark) to inspect mDNS traffic on port 5353.

• TypeError: bonjour is not a function

  cause This error occurs when `require('bonjour')` or `import bonjour from 'bonjour'` is not immediately invoked as a function to create the instance.
  fix Use `const bonjour = require('bonjour')();` for CommonJS or `import bonjourFactory from 'bonjour'; const bonjour = bonjourFactory();` for ESM to correctly initialize the Bonjour instance.

Warnings

• gotcha The `bonjour` factory function (`require('bonjour')()` or `bonjourFactory()`) creates an instance. It is crucial to call `bonjour.destroy()` when the application exits or the Bonjour functionality is no longer needed, to properly close the underlying UDP socket and stop broadcasting, preventing resource leaks.
  Fix: Always ensure `bonjour.destroy()` is called on application shutdown, for instance, by listening to `process.on('exit')` or `process.on('SIGINT')`.
• gotcha Bonjour relies on UDP multicast, which can be affected by network configurations, firewalls, and VPNs. Services might not be discoverable across different subnets or through restrictive network policies.
  Fix: Verify network settings, ensure UDP ports are open (typically 5353 for mDNS), and test within the same local subnet. Avoid using VPNs during development if Bonjour discovery is critical.
• gotcha Service advertisements might not be immediately visible, and discovery can take a few seconds as it relies on multicast DNS broadcasts. Conversely, 'down' events for services are not always instantaneous, as a device might disappear without sending a 'goodbye' message.
  Fix: Implement robust handling for service presence, assuming services might appear or disappear with some delay. Consider a debounce or timeout mechanism for reacting to service discovery events.
• deprecated While `bonjour` is still active, an official rewrite in TypeScript named `bonjour-service` is available. For new projects, especially those using TypeScript, `bonjour-service` might be a more modern and actively developed alternative with better RFC compliance.
  Fix: For new projects, consider `npm install bonjour-service` and consult its documentation for usage. For existing projects, be aware that `bonjour` may not receive significant new features or compliance updates.

Install

• npm install bonjour npm
• yarn add bonjour yarn
• pnpm add bonjour pnpm

Imports

• bonjourFactory
  wrong:

  import { bonjour } from 'bonjour'; // Incorrect named import
  const bonjour = new bonjour();    // Not a class

  correct:

  import bonjourFactory from 'bonjour';
  const bonjour = bonjourFactory();

  The default export is a factory function that needs to be called to get the Bonjour instance. TypeScript users may need `import bonjourFactory = require('bonjour');` or configure `esModuleInterop`.
• bonjourInstance
  wrong:

  const bonjour = require('bonjour'); // Missing function call
  const { publish } = require('bonjour'); // No named exports for methods

  correct:

  const bonjour = require('bonjour')();

  In CommonJS, `require('bonjour')` returns a factory function that must be immediately invoked to get the Bonjour instance with its methods (`publish`, `find`, etc.).
• Service
  wrong:

  import { Service } from 'bonjour'; // Not directly exported

  correct:

  const service = bonjour.publish(...);

  Service objects are returned by `bonjour.publish()` and `browser.on('up', ...)` events. They are not directly importable classes.

Quickstart

This quickstart demonstrates how to initialize `bonjour`, publish an HTTP service, and then discover existing HTTP services on the local network, with proper cleanup.

import bonjourFactory from 'bonjour';

const bonjour = bonjourFactory();

// Advertise an HTTP server on port 3000
const service = bonjour.publish({
  name: 'My Bonjour Web Server',
  type: 'http',
  port: 3000,
  txt: { version: '1.0', path: '/' }
});

service.on('up', () => {
  console.log('Service published:', service.name, service.host, service.port);
});

// Browse for all http services
const browser = bonjour.find({ type: 'http' });

browser.on('up', (foundService) => {
  console.log('Found an HTTP server:', foundService.name, foundService.host, foundService.port);
});

// Stop browsing after 10 seconds and destroy all services/connections
setTimeout(() => {
  console.log('Stopping discovery and unpublishing service...');
  browser.stop();
  bonjour.unpublishAll(() => {
    console.log('All services unpublished.');
    bonjour.destroy(); // Close the UDP socket
    console.log('Bonjour instance destroyed.');
  });
}, 10000);

// Handle process exit to ensure cleanup
process.on('SIGINT', () => {
  console.log('Received SIGINT. Destroying Bonjour instance...');
  bonjour.destroy();
  process.exit();
});