capacitor-zeroconf

A Capacitor plugin for ZeroConf/Bonjour/mDNS service discovery and publishing.

Features

• Discover services on your local network using mDNS/Bonjour
• Publish services to make your app discoverable by other devices
• Cross-platform support for iOS, Android, and Electron
• Event-driven architecture with proper service discovery callbacks
• TypeScript support with full type definitions

Platform Support

Platform	Supported
iOS	✅
Android	✅
Electron	✅
Web	❌

Note: This plugin requires native platform capabilities and does not work in web browsers. Service discovery and publishing operations are automatically stopped when the application is terminated or goes into the background.

Install

Install directly from this GitHub repository to get the latest fixes:

npm install byrdsandbytes/capacitor-zeroconf
npx cap sync

or

yarn add byrdsandbytes/capacitor-zeroconf
yarn cap sync

Quick Start

Discovering Services

import { ZeroConf } from 'capacitor-zeroconf';

// Set up listener for discovered services
const listener = await ZeroConf.addListener('discover', (result) => {
  console.log(`Service ${result.action}:`, result.service.name);
  
  if (result.action === 'resolved') {
    console.log('Service details:', {
      name: result.service.name,
      host: result.service.hostname,
      port: result.service.port,
      addresses: result.service.ipv4Addresses
    });
  }
});

// Start watching for HTTP services
await ZeroConf.watch({
  type: '_http._tcp.',
  domain: 'local.'
});

// Stop watching
await ZeroConf.unwatch({
  type: '_http._tcp.',
  domain: 'local.'
});

// Clean up
listener.remove();

Publishing Services

// Publish your app as a discoverable service
await ZeroConf.register({
  type: '_http._tcp.',
  domain: 'local.',
  name: 'My App',
  port: 8080,
  props: {
    description: 'My awesome app',
    version: '1.0.0'
  }
});

// Stop publishing
await ZeroConf.unregister({
  type: '_http._tcp.',
  domain: 'local.',
  name: 'My App'
});

Important Notes

⚠️ Breaking Change Fix: This fork fixes a critical issue where the watch() method only returned the first discovered service. The native implementations now properly emit all discovered services as events through the addListener('discover', ...) pattern.

Migration Guide: If you were using the old version and only getting the first result, no code changes are needed - you'll now receive all discovered services as expected.

API

• addListener('discover', ...)
• getHostname()
• register(...)
• unregister(...)
• stop()
• watch(...)
• unwatch(...)
• close()
• Interfaces
• Type Aliases

ZeroConf/Bonjour/mDNS service discovery and publishing plugin

addListener('discover', ...)

addListener(eventName: 'discover', listenerFunc: (result: ZeroConfWatchResult) => void) => Promise<PluginListenerHandle>

Listen for service discovery events

Param	Type	Description
eventName	'discover'	- Must be 'discover'
listenerFunc	(result: ZeroConfWatchResult) => void	- Callback function for discovery events

Returns: Promise<PluginListenerHandle>

---

getHostname()

getHostname() => Promise<{ hostname: string; }>

Get the device hostname

Returns: Promise<{ hostname: string; }>

---

register(...)

register(request: ZeroConfRegisterRequest) => Promise<void>

Register/publish a service to make it discoverable

Param	Type	Description
request	ZeroConfRegisterRequest	- Service registration details

---

unregister(...)

unregister(request: ZeroConfUnregisterRequest) => Promise<void>

Unregister/unpublish a previously registered service

Param	Type	Description
request	ZeroConfUnregisterRequest	- Service to unregister

---

stop()

stop() => Promise<void>

Stop all service registration/publishing

---

watch(...)

watch(request: ZeroConfWatchRequest, callback?: ZeroConfWatchCallback | undefined) => Promise<CallbackID>

Start watching for services of a specific type Use addListener('discover', ...) to receive the discovered services

Param	Type	Description
request	ZeroConfWatchRequest	- What services to watch for
callback	ZeroConfWatchCallback	- Optional callback (deprecated, use addListener instead)

Returns: Promise<string>

---

unwatch(...)

unwatch(request: ZeroConfUnwatchRequest) => Promise<void>

Stop watching for services

Param	Type	Description
request	ZeroConfWatchRequest	- What services to stop watching

---

close()

close() => Promise<void>

Close all operations and cleanup resources

---

Interfaces

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

ZeroConfWatchResult

Result of a service discovery event

Prop	Type	Description
action	ZeroConfWatchAction	What happened to the service
service	ZeroConfService	The service that was affected

ZeroConfService

Discovered service information

Prop	Type	Description
domain	string	Domain of the service
type	string	Service type
name	string	Service name
port	number	Port number
hostname	string	Hostname/FQDN
ipv4Addresses	string[]	IPv4 addresses
ipv6Addresses	string[]	IPv6 addresses
txtRecord	Record<string, string>	TXT record data

ZeroConfRegisterRequest

Request to register/publish a service

Prop	Type	Description
port	number	Port number the service is running on
props	Record<string, string>	Additional properties/metadata for the service

ZeroConfUnregisterRequest

Request to unregister a published service

Prop	Type	Description
name	string	Name of the service to unregister

ZeroConfWatchRequest

Request to watch for services of a specific type

Prop	Type	Description
type	string	Service type (e.g., '_http._tcp.', '_ssh._tcp.')
domain	string	Domain to search in (typically 'local.')

Type Aliases

ZeroConfWatchAction

Actions that can occur during service discovery

'added' | 'removed' | 'resolved'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

ZeroConfWatchCallback

Callback function for service discovery events

(event: ZeroConfWatchResult): void

CallbackID

Unique identifier for a watch operation

string

ZeroConfUnwatchRequest

Request to stop watching for services Same as ZeroConfWatchRequest

ZeroConfWatchRequest

Contributing

This is a fork of the original capacitor-zeroconf plugin with critical bug fixes for service discovery.

Recent Improvements

• ✅ Fixed service discovery: All discovered services are now properly returned (not just the first one)
• ✅ Proper event emission: Native implementations now use notifyListeners() correctly
• ✅ Better TypeScript support: Improved type definitions and error handling
• ✅ Updated documentation: Modern terminology and better examples

License

MIT License

This project is licensed under the MIT License - the same license as the original cordova-plugin-zeroconf plugin.

Credits

Originally ported from the Cordova ZeroConf Plugin and based on capacitor-zeroconf by Marco Marche.