Node.js dns Module Guide

The dns module provides DNS resolution and lookup capabilities. Here's how to use it for network operations.

Basic Lookup#

import dns from 'node:dns';
import { promisify } from 'node:util';

const lookup = promisify(dns.lookup);

// Simple lookup
async function resolveHostname(hostname) {
  try {
    const result = await lookup(hostname);
    console.log('Address:', result.address);
    console.log('Family:', result.family); // 4 or 6
    return result;
  } catch (error) {
    console.error('Lookup failed:', error.message);
    throw error;
  }
}

await resolveHostname('google.com');
// Address: 142.250.80.46
// Family: 4

Promise-based API#

import dns from 'node:dns/promises';

// Use promises API directly
async function dnsOperations() {
  // Lookup
  const address = await dns.lookup('example.com');
  console.log('IP:', address.address);

  // Resolve multiple record types
  const mx = await dns.resolveMx('gmail.com');
  console.log('MX records:', mx);

  const txt = await dns.resolveTxt('google.com');
  console.log('TXT records:', txt);
}

Lookup Options#

import dns from 'node:dns/promises';

// IPv4 only
const ipv4 = await dns.lookup('google.com', { family: 4 });
console.log('IPv4:', ipv4.address);

// IPv6 only
const ipv6 = await dns.lookup('google.com', { family: 6 });
console.log('IPv6:', ipv6.address);

// All addresses
const all = await dns.lookup('google.com', { all: true });
console.log('All addresses:', all);
// [{ address: '...', family: 4 }, { address: '...', family: 6 }]

// With hints
const hints = await dns.lookup('google.com', {
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
});

Resolve DNS Records#

import dns from 'node:dns/promises';

// A records (IPv4)
async function resolveA(hostname) {
  const addresses = await dns.resolve4(hostname);
  console.log('A records:', addresses);
  return addresses;
}

// AAAA records (IPv6)
async function resolveAAAA(hostname) {
  const addresses = await dns.resolve6(hostname);
  console.log('AAAA records:', addresses);
  return addresses;
}

// MX records (mail)
async function resolveMX(hostname) {
  const records = await dns.resolveMx(hostname);
  console.log('MX records:', records);
  // [{ exchange: 'mail.example.com', priority: 10 }]
  return records.sort((a, b) => a.priority - b.priority);
}

// TXT records
async function resolveTXT(hostname) {
  const records = await dns.resolveTxt(hostname);
  console.log('TXT records:', records);
  return records.flat();
}

// NS records (nameservers)
async function resolveNS(hostname) {
  const nameservers = await dns.resolveNs(hostname);
  console.log('NS records:', nameservers);
  return nameservers;
}

// CNAME records
async function resolveCNAME(hostname) {
  try {
    const cname = await dns.resolveCname(hostname);
    console.log('CNAME:', cname);
    return cname;
  } catch (error) {
    if (error.code === 'ENODATA') {
      return null; // No CNAME record
    }
    throw error;
  }
}

SOA Records#

import dns from 'node:dns/promises';

async function getSOA(domain) {
  const soa = await dns.resolveSoa(domain);
  console.log('SOA Record:');
  console.log('  Primary NS:', soa.nsname);
  console.log('  Admin:', soa.hostmaster);
  console.log('  Serial:', soa.serial);
  console.log('  Refresh:', soa.refresh);
  console.log('  Retry:', soa.retry);
  console.log('  Expire:', soa.expire);
  console.log('  Min TTL:', soa.minttl);
  return soa;
}

await getSOA('google.com');

SRV Records#

import dns from 'node:dns/promises';

async function resolveSRV(service) {
  const records = await dns.resolveSrv(service);

  // Sort by priority, then weight
  records.sort((a, b) => {
    if (a.priority !== b.priority) {
      return a.priority - b.priority;
    }
    return b.weight - a.weight;
  });

  console.log('SRV records:');
  records.forEach((r) => {
    console.log(`  ${r.name}:${r.port} (priority: ${r.priority}, weight: ${r.weight})`);
  });

  return records;
}

// Example: XMPP server discovery
await resolveSRV('_xmpp-server._tcp.gmail.com');

Reverse DNS Lookup#

import dns from 'node:dns/promises';

async function reverseLookup(ip) {
  try {
    const hostnames = await dns.reverse(ip);
    console.log(`${ip} resolves to:`, hostnames);
    return hostnames;
  } catch (error) {
    if (error.code === 'ENOTFOUND') {
      console.log(`No PTR record for ${ip}`);
      return [];
    }
    throw error;
  }
}

await reverseLookup('8.8.8.8');
// ['dns.google']

Resolve Any Record Type#

import dns from 'node:dns/promises';

async function resolveAny(hostname) {
  try {
    const records = await dns.resolveAny(hostname);

    records.forEach((record) => {
      console.log(`${record.type}:`, record);
    });

    return records;
  } catch (error) {
    console.error('Failed to resolve:', error.message);
    throw error;
  }
}

// Get all available records
await resolveAny('google.com');

Custom DNS Servers#

import dns from 'node:dns';
import { Resolver } from 'node:dns/promises';

// Create resolver with custom servers
const resolver = new Resolver();
resolver.setServers(['8.8.8.8', '8.8.4.4']); // Google DNS

async function lookupWithCustomDNS(hostname) {
  const addresses = await resolver.resolve4(hostname);
  console.log('Using custom DNS:', addresses);
  return addresses;
}

// Get current DNS servers
console.log('Current servers:', dns.getServers());

// Set servers globally (affects all lookups)
dns.setServers(['1.1.1.1', '1.0.0.1']); // Cloudflare DNS

DNS Cache#

import dns from 'node:dns/promises';

class DNSCache {
  constructor(ttl = 60000) {
    this.cache = new Map();
    this.ttl = ttl;
  }

  async lookup(hostname, options = {}) {
    const key = `${hostname}-${options.family || 'any'}`;
    const cached = this.cache.get(key);

    if (cached && Date.now() < cached.expires) {
      console.log('Cache hit:', hostname);
      return cached.result;
    }

    console.log('Cache miss:', hostname);
    const result = await dns.lookup(hostname, options);

    this.cache.set(key, {
      result,
      expires: Date.now() + this.ttl,
    });

    return result;
  }

  async resolve4(hostname) {
    const key = `A-${hostname}`;
    const cached = this.cache.get(key);

    if (cached && Date.now() < cached.expires) {
      return cached.result;
    }

    const result = await dns.resolve4(hostname);
    this.cache.set(key, {
      result,
      expires: Date.now() + this.ttl,
    });

    return result;
  }

  clear() {
    this.cache.clear();
  }
}

const dnsCache = new DNSCache(300000); // 5 minute TTL

Health Check with DNS#

import dns from 'node:dns/promises';

async function checkDNSHealth(hostname, expectedIPs = []) {
  const startTime = Date.now();

  try {
    const result = await dns.lookup(hostname, { all: true });
    const duration = Date.now() - startTime;

    const ips = result.map((r) => r.address);
    const hasExpected = expectedIPs.every((ip) => ips.includes(ip));

    return {
      hostname,
      healthy: true,
      duration,
      addresses: ips,
      expectedMatch: hasExpected,
    };
  } catch (error) {
    return {
      hostname,
      healthy: false,
      duration: Date.now() - startTime,
      error: error.message,
      code: error.code,
    };
  }
}

async function monitorDNS(hostnames, interval = 30000) {
  setInterval(async () => {
    for (const hostname of hostnames) {
      const health = await checkDNSHealth(hostname);
      if (!health.healthy) {
        console.error(`DNS health check failed for ${hostname}:`, health);
      }
    }
  }, interval);
}

Error Handling#

import dns from 'node:dns/promises';

async function safeLookup(hostname) {
  try {
    return await dns.lookup(hostname);
  } catch (error) {
    switch (error.code) {
      case 'ENOTFOUND':
        console.error(`Hostname not found: ${hostname}`);
        break;
      case 'ENODATA':
        console.error(`No data for: ${hostname}`);
        break;
      case 'ETIMEOUT':
        console.error(`DNS timeout for: ${hostname}`);
        break;
      case 'ESERVFAIL':
        console.error(`DNS server failure for: ${hostname}`);
        break;
      case 'ECONNREFUSED':
        console.error(`DNS connection refused for: ${hostname}`);
        break;
      default:
        console.error(`DNS error for ${hostname}:`, error.message);
    }
    throw error;
  }
}

// With retry
async function lookupWithRetry(hostname, retries = 3, delay = 1000) {
  for (let i = 0; i < retries; i++) {
    try {
      return await dns.lookup(hostname);
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Best Practices#

Lookup vs Resolve:
✓ lookup() uses OS resolver (cached)
✓ resolve() queries DNS directly
✓ Use lookup() for general use
✓ Use resolve() for specific records

Performance:
✓ Cache DNS results
✓ Use connection pooling
✓ Set reasonable timeouts
✓ Handle failures gracefully

Error Handling:
✓ Check error.code
✓ Implement retries
✓ Log DNS failures
✓ Have fallback servers

Avoid:
✗ Hardcoding IPs
✗ Ignoring TTLs
✗ Blocking on DNS
✗ No timeout handling

The Node.js dns module provides comprehensive DNS resolution capabilities. Use lookup() for general hostname resolution with OS caching, and resolve*() methods for specific record types. Implement caching for performance, handle errors with retry logic, and use custom resolvers for specific DNS servers. The promises API makes async DNS operations clean and composable for modern Node.js applications.