bonjour

library0.0.3jsnpmunverified

The `bonjour` package provides a pure JavaScript implementation of the Bonjour (also known as Zeroconf or mDNS/DNS-SD) protocol for Node.js environments. It allows applications to publish services on the local network, making them discoverable by other Bonjour-compatible devices, and to discover services advertised by others. The library is currently at version 3.5.1 and has an infrequent, as-needed release cadence. Its key differentiator is its full implementation in JavaScript, relying on the `multicast-dns` package for the underlying DNS operations. Unlike some alternatives, it offers both service advertisement and discovery capabilities within a single, lightweight API, making it suitable for local network peer-to-peer communication without central servers.

http-networking devops

npm install bonjour

github ↗package ↗

INSTALL

IMPORT

SIG · BONJOUR

bonjour

http-networkingjavascriptv0.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bonjourFactory

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

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

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

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

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

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

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

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

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

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(); });

Debug

Known issues

gotchaThe `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')`.

affects: >=1.0.0

gotchaBonjour 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.

affects: >=1.0.0

gotchaService 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.

affects: >=1.0.0

deprecatedWhile `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.

affects: >=3.0.0

Errors

Common errors & fixes

Error: bind EADDRINUSE 0.0.0.0:5353

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.

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

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.

Upgrade

Version history

0.0.3latest on npm

Audit

Dependencies

multicast-dnsrequiredCore dependency for multicast DNS communication.

dns-txtrequiredUsed for parsing and formatting DNS TXT records.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/watson/bonjour ↗

packagehttps://www.npmjs.com/package/bonjour ↗