Bonjour/Zeroconf Service Discovery for Node.js

Common errors

• Error: bind EADDRINUSE 0.0.0.0:5353

  cause Another process is already using the mDNS port (5353). This is common if another mDNS client or server is running.
  fix Ensure only one instance of `bonjour-service` (or any other mDNS client/server) is running at a time. If running multiple, ensure each `Bonjour` instance has its own unique port configuration if necessary, though mDNS typically operates on 5353. For system-wide conflicts, identify and stop the conflicting process.

• Error: no such host

  cause When browsing for services, the `host` property might sometimes appear as 'no such host' if the mDNS resolver couldn't immediately resolve the hostname from the IP address, or if the host went offline before a full resolution could occur.
  fix This is often transient. Ensure the target device is online and accessible on the local network. Implement retries or a more robust service tracking logic in your application to handle temporary resolution failures.

• TypeError: Bonjour is not a constructor

  cause Attempting to use `require()` with an ES module or incorrect destructuring in CommonJS.
  fix If using CommonJS, try `const { Bonjour } = require('bonjour-service');`. If using ES modules, ensure your environment supports `import` syntax and you are using `import { Bonjour } from 'bonjour-service';`.

Warnings

• gotcha Firewall rules can prevent `bonjour-service` from functioning correctly, as it relies on multicast UDP on port 5353. Ensure this port is open for both inbound and outbound traffic if services are not being discovered or published.
  Fix: Adjust firewall settings to allow UDP traffic on port 5353 for the Node.js process. On Linux, consider `sudo ufw allow 5353/udp`.
• gotcha The `Bonjour` constructor can optionally take an `errorCallback` to handle errors gracefully that would otherwise crash the process, particularly issues with the underlying `multicast-dns` server. It is highly recommended to provide this callback.
  Fix: Initialize Bonjour with an error callback: `const bonjour = new Bonjour({}, (err) => console.error('Bonjour error:', err));`
• gotcha When publishing services, ensure the `name` is unique on the network for a given `type` and `protocol` to avoid conflicts. Duplicate service names can lead to unpredictable behavior or services not being properly advertised.
  Fix: Dynamically generate or append a unique identifier (e.g., hostname, UUID) to service names, especially in environments where multiple instances of the same service might run concurrently.
• gotcha The `destroy()` method is crucial for releasing network resources. Failing to call `destroy()` on the `Bonjour` instance (and `stop()` on individual services/browsers) can leave UDP sockets open, leading to resource leaks or preventing process exit.
  Fix: Always call `bonjour.destroy()` when your application is shutting down or no longer needs service discovery/publishing. For individual services/browsers, use `service.stop()` and `browser.stop()`.

Install

• npm install bonjour-service npm
• yarn add bonjour-service yarn
• pnpm add bonjour-service pnpm

Imports

• Bonjour
  wrong:

  const Bonjour = require('bonjour-service')

  correct:

  import { Bonjour } from 'bonjour-service'

  The library is primarily designed for ESM with TypeScript. While CommonJS `require` might work in some environments, `import` is the idiomatic and fully supported way.
• Service
  wrong:

  import { Service } from 'bonjour-service'

  correct:

  import type { Service } from 'bonjour-service'

  When importing types for type annotations, use `import type` to ensure it's not bundled as a runtime import, especially critical for tree-shaking and avoiding issues in strict ESM setups.
• Options

  import type { BonjourOptions } from 'bonjour-service'

  Type for the constructor options, useful for strict TypeScript environments.

Quickstart

This quickstart demonstrates how to publish an HTTP service and simultaneously discover other HTTP services on the local network using `bonjour-service`.

import { Bonjour } from 'bonjour-service';
import { createServer } from 'http';

const bonjour = new Bonjour();
const server = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from bonjour-service!');
});

const port = 3000;
server.listen(port, () => {
  console.log(`HTTP server listening on port ${port}`);
  // Advertise an HTTP server on port 3000
  const publishedService = bonjour.publish({
    name: 'My bonjour-service Web Server',
    type: 'http',
    port: port,
    txt: { version: '1.0', path: '/' }
  });
  publishedService.on('up', () => {
    console.log(`Service '${publishedService.name}' published successfully.`);
  });

  // Browse for all http services
  const browser = bonjour.find({ type: 'http' });
  browser.on('up', (service) => {
    console.log('Found an HTTP server:', service.name, service.port, service.host);
  });

  // Stop browsing and unpublish after a delay
  setTimeout(() => {
    console.log('Stopping services...');
    browser.stop();
    publishedService.stop();
    bonjour.destroy();
    server.close(() => console.log('HTTP server closed.'));
  }, 15000);
});