@laravelka/zeroconf

Capacitor plugin for Zeroconf (mDNS) service discovery and broadcasting.

Install

npm install @laravelka/zeroconf
npx cap sync

iOS Setup

Prerequisites

• Xcode 15.0+
• CocoaPods

Configuration

1. Open your project in Xcode:

npx cap open ios

2. Add the following keys to your Info.plist file:

<!-- Local Network Usage Description -->
<key>NSLocalNetworkUsageDescription</key>
<string>This app needs access to find and connect to local network devices</string>

<!-- Bonjour Services -->
<key>NSBonjourServices</key>
<array>
    <string>_http._tcp.</string>
    <!-- Add other service types your app will use -->
</array>

Android Setup

Prerequisites

• Android Studio Electric Eel (2022.1.1) or newer
• Android SDK and Platform Tools installed
• Java 17 or newer

Configuration

1. Open your project in Android Studio:

npx cap open android

2. Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<!-- Required permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

3. Update your android/variables.gradle to ensure compatibility:

ext {
    minSdkVersion = 26
    compileSdkVersion = 34
    targetSdkVersion = 34
    androidxActivityVersion = '1.7.0'
}

4. Make sure your android/build.gradle has the correct Java version:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

Usage

import { ZeroConf } from '@laravelka/zeroconf';
import type { PluginListenerHandle, ZeroConfWatchResult } from '@laravelka/zeroconf';

let listener: PluginListenerHandle;

// Listen for service discovery events
const setupListeners = async () => {
  listener = await ZeroConf.addListener('discover', (result: ZeroConfWatchResult) => {
    console.log('Service discovered:', result);
    // result.action will be 'added', 'removed', or 'resolved'
    // result.service contains service information
  });
};

// Register a service
await ZeroConf.register({
  type: '_http._tcp.',
  domain: 'local.',
  name: 'MyService',
  port: 3000,
  txtRecord: {
    path: '/api'
  }
});

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

// Cleanup listeners when done
await listener?.remove();

// Later: stop watching and cleanup
await ZeroConf.unwatch({
  type: '_http._tcp.',
  domain: 'local.'
});

await ZeroConf.unregister({
  type: '_http._tcp.',
  domain: 'local.',
  name: 'MyService'
});

// Stop all discoveries and unregister all services
await ZeroConf.stop();

// Clean up resources when done
await ZeroConf.close();

Configuration

Add the following to your capacitor.config.ts:

/// <reference types="@laravelka/zeroconf" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    ZeroConf: {
      // Optional configuration options can be added here
    }
  }
};

export default config;

API

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

Main ZeroConf plugin interface.

addListener('discover', ...)

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

Add a listener for service discovery events.

| Param | Type | Description | | ------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | eventName | 'discover' | - The name of the event to listen for | | listenerFunc | (result: ZeroConfWatchResult) => void | - Callback function that will be called when a service is discovered |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

getHostname()

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

Get the hostname of the device.

Returns: Promise<{ hostname: string; }>

Since: 1.0.0

register(...)

register(options: { type: string; domain?: string | undefined; name: string; port: number; txtRecord?: { [key: string]: string; } | undefined; }) => Promise<void>

Register a new service.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | options | { type: string; domain?: string; name: string; port: number; txtRecord?: { [key: string]: string; }; } | - Service registration options |

Since: 1.0.0

unregister(...)

unregister(options: { type: string; name: string; }) => Promise<void>

Unregister a previously registered service.

| Param | Type | Description | | ------------- | -------------------------------------------- | -------------------------------- | | options | { type: string; name: string; } | - Service unregistration options |

Since: 1.0.0

watch(...)

watch(options: { type: string; domain?: string; }) => Promise<void>

Start watching for services of a specific type.

| Param | Type | Description | | ------------- | ----------------------------------------------- | ----------------------- | | options | { type: string; domain?: string; } | - Service watch options |

Since: 1.0.0

unwatch(...)

unwatch(options: { type: string; }) => Promise<void>

Stop watching for services of a specific type.

| Param | Type | Description | | ------------- | ------------------------------ | ------------------------- | | options | { type: string; } | - Service unwatch options |

Since: 1.0.0

stop()

stop() => Promise<void>

Stop all ongoing service discoveries and unregister all services.

Since: 1.0.0

close()

close() => Promise<void>

Close the Zeroconf instance and clean up resources.

Since: 1.0.0

Interfaces

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

ZeroConfWatchResult

Result of a ZeroConf service discovery event.

| Prop | Type | | ------------- | ----------------------------------------------------------- | | action | 'added' | 'removed' | 'resolved' | | service | ZeroConfService |

ZeroConfService

Represents a discovered ZeroConf service.

| Prop | Type | | ------------------- | --------------------------------------- | | domain | string | | type | string | | name | string | | port | number | | hostname | string | | ipv4Addresses | string[] | | ipv6Addresses | string[] | | txtRecord | { [key: string]: string; } |

Example Usage

import { ZeroConf } from '@laravelka/zeroconf';
import type { PluginListenerHandle, ZeroConfWatchResult } from '@laravelka/zeroconf';

class ZeroConfExample {
  private listener: PluginListenerHandle | null = null;

  async initialize() {
    // Setup event listener
    this.listener = await ZeroConf.addListener('discover', (result: ZeroConfWatchResult) => {
      console.log('Service discovered:', result);
      // result.action will be 'added', 'removed', or 'resolved'
      // result.service contains service information
    });

    // Register our service
    await ZeroConf.register({
      type: '_http._tcp.',
      domain: 'local.',
      name: 'MyService',
      port: 3000,
      txtRecord: {
        path: '/api'
      }
    });

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

  async cleanup() {
    // Remove event listener
    if (this.listener) {
      await this.listener.remove();
      this.listener = null;
    }

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

    // Unregister our service
    await ZeroConf.unregister({
      type: '_http._tcp.',
      domain: 'local.',
      name: 'MyService'
    });

    // Stop all discoveries and unregister all services
    await ZeroConf.stop();

    // Clean up resources
    await ZeroConf.close();
  }
}

Platform Support

• ✅ Android (using JmDNS)
• ✅ iOS (using Network.framework and NetService)

Requirements

• Capacitor 7.0.0 or newer
• iOS 13.0 or newer (Xcode 15.0+)
• Android API 26 (Android 8.0) or newer

License

MIT