stupid-mdns

A very simple, zero-dependency mDNS responder library written in TypeScript.

This library was made for a specific purpose but is shared in the hope that it might be useful to others who need a lightweight mDNS responder without complex dependencies. Might lack features or testing. Feel free to contribute fixes and improvements.

Installation

npm install stupid-mdns
# or
pnpm add stupid-mdns
# or
yarn add stupid-mdns

Usage

Here is a simple example of how to create an mDNS responder that announces a hostname with IPv4 and IPv6 addresses.

import {
  createMdnsServer,
  DNS_CLASS_CACHE_FLUSH,
  DNS_CLASS_IN,
  DNS_TYPE_A,
  DNS_TYPE_AAAA,
  encodeIPv4,
  encodeIPv6,
} from "stupid-mdns";

async function main() {
  // Create the server instance
  const server = createMdnsServer({
    hostname: "my-device", // will become my-device.local
  });

  // Define what records to respond with
  server.setAnnouncementCallback((ctx) => {
    // Add A record (IPv4)
    ctx.pushAnswerRecord({
      type: DNS_TYPE_A,
      classValue: DNS_CLASS_IN | DNS_CLASS_CACHE_FLUSH,
      ttlSeconds: ctx.ttlSeconds,
      rdata: encodeIPv4("192.168.1.50"),
    });

    // Add AAAA record (IPv6)
    ctx.pushAnswerRecord({
      type: DNS_TYPE_AAAA,
      classValue: DNS_CLASS_IN | DNS_CLASS_CACHE_FLUSH,
      ttlSeconds: ctx.ttlSeconds,
      rdata: encodeIPv6("fe80::1"),
    });
  });

  // Start the server
  await server.start();
  console.log("mDNS responder started for my-device.local");

  // Handle shutdown gracefully
  process.on("SIGINT", async () => {
    await server.stop();
    process.exit(0);
  });
}

main();

API

createMdnsServer(options)

Creates a new mDNS server instance.

Options:

• hostname (string): The hostname to announce (e.g., "my-device"). Automatically appended with ".local.".
• interface4 (string, optional): Specific network interface for IPv4.
• interface6 (string, optional): Specific network interface for IPv6.
• ttlSeconds (number, optional): Default TTL for records (default: 120).
• debugLog (function, optional): Callback for debug logs.

server.setAnnouncementCallback(callback)

Sets the callback function that constructs the DNS records for announcements and query responses.

The callback receives a context object with:

• hostname: The full hostname (e.g., "my-device.local.").
• ttlSeconds: Recommended TTL.
• cacheFlush: Whether to set the cache-flush bit (use for multicast/announcement).
• pushAnswerRecord(record): Add a record to the answer section.
• pushAdditionalRecord(record): Add a record to the additional section.

server.start()

Starts the mDNS server, binds sockets, and sends initial announcements.

server.stop()

Stops the server, sends goodbye packets (TTL=0), and closes sockets.

server.reannounce()

Sends multicast announcements immediately (e.g. after records change). No-op if the server is not started.