Node.js DNS Module Guide

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

Basic Lookups#

const dns = require('dns');
const { promisify } = require('util');

// Callback-based lookup
dns.lookup('google.com', (err, address, family) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(`Address: ${address}, Family: IPv${family}`);
});

// Promise-based lookup
const lookupAsync = promisify(dns.lookup);

async function lookup(hostname) {
  try {
    const { address, family } = await lookupAsync(hostname);
    console.log(`Address: ${address}, Family: IPv${family}`);
    return address;
  } catch (err) {
    console.error(`Lookup failed: ${err.message}`);
    throw err;
  }
}

// Using dns.promises (Node.js 10.6+)
const dnsPromises = require('dns').promises;

async function lookupModern(hostname) {
  const result = await dnsPromises.lookup(hostname);
  return result.address;
}

IP Version Options#

const dns = require('dns').promises;

// Get IPv4 address
async function getIPv4(hostname) {
  const { address } = await dns.lookup(hostname, { family: 4 });
  return address;
}

// Get IPv6 address
async function getIPv6(hostname) {
  const { address } = await dns.lookup(hostname, { family: 6 });
  return address;
}

// Get all addresses
async function getAllAddresses(hostname) {
  const addresses = await dns.lookup(hostname, { all: true });
  return addresses;
  // [{ address: '172.217.14.110', family: 4 }, ...]
}

// With hints
async function lookupWithHints(hostname) {
  const { address } = await dns.lookup(hostname, {
    hints: dns.ADDRCONFIG | dns.V4MAPPED,
  });
  return address;
}

DNS Resolution#

const dns = require('dns').promises;

// Resolve A records (IPv4)
async function resolveA(hostname) {
  const addresses = await dns.resolve4(hostname);
  return addresses; // ['172.217.14.110', ...]
}

// Resolve AAAA records (IPv6)
async function resolveAAAA(hostname) {
  const addresses = await dns.resolve6(hostname);
  return addresses;
}

// Resolve MX records (mail)
async function resolveMX(hostname) {
  const records = await dns.resolveMx(hostname);
  return records;
  // [{ priority: 10, exchange: 'mail.example.com' }, ...]
}

// Resolve TXT records
async function resolveTXT(hostname) {
  const records = await dns.resolveTxt(hostname);
  return records;
  // [['v=spf1 include:_spf.google.com ~all'], ...]
}

// Resolve CNAME records
async function resolveCNAME(hostname) {
  const records = await dns.resolveCname(hostname);
  return records; // ['www.example.com']
}

// Resolve NS records (name servers)
async function resolveNS(hostname) {
  const records = await dns.resolveNs(hostname);
  return records; // ['ns1.example.com', 'ns2.example.com']
}

// Resolve SOA record (Start of Authority)
async function resolveSOA(hostname) {
  const record = await dns.resolveSoa(hostname);
  return record;
  // { nsname, hostmaster, serial, refresh, retry, expire, minttl }
}

// Resolve SRV records
async function resolveSRV(hostname) {
  const records = await dns.resolveSrv(hostname);
  return records;
  // [{ priority, weight, port, name }, ...]
}

Generic Resolution#

const dns = require('dns').promises;

// Resolve any record type
async function resolveAny(hostname) {
  const records = await dns.resolveAny(hostname);
  return records;
  // Mixed array of all record types
}

// Resolve specific type
async function resolve(hostname, recordType) {
  const records = await dns.resolve(hostname, recordType);
  return records;
}

// Usage
await resolve('example.com', 'A');
await resolve('example.com', 'MX');
await resolve('example.com', 'TXT');

// Available record types:
// 'A', 'AAAA', 'ANY', 'CAA', 'CNAME', 'MX', 'NAPTR',
// 'NS', 'PTR', 'SOA', 'SRV', 'TXT'

Reverse DNS Lookup#

const dns = require('dns').promises;

// IP to hostname
async function reverseLookup(ip) {
  try {
    const hostnames = await dns.reverse(ip);
    return hostnames; // ['hostname.example.com']
  } catch (err) {
    if (err.code === 'ENOTFOUND') {
      return null; // No reverse DNS entry
    }
    throw err;
  }
}

// Get PTR records
async function resolvePTR(ip) {
  const records = await dns.resolvePtr(ip);
  return records;
}

Custom DNS Servers#

const dns = require('dns');
const { Resolver } = dns;

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

// Use custom resolver
resolver.resolve4('example.com', (err, addresses) => {
  console.log(addresses);
});

// Promise-based custom resolver
const { promisify } = require('util');
const resolve4Async = promisify(resolver.resolve4.bind(resolver));

async function resolveWithGoogle(hostname) {
  return resolve4Async(hostname);
}

// Get current DNS servers
console.log(dns.getServers());
// ['192.168.1.1', '8.8.8.8']

// Set default servers
dns.setServers(['1.1.1.1', '1.0.0.1']); // Cloudflare DNS

Error Handling#

const dns = require('dns').promises;

async function safeLookup(hostname) {
  try {
    const result = await dns.lookup(hostname);
    return { success: true, ...result };
  } catch (err) {
    return {
      success: false,
      code: err.code,
      message: getErrorMessage(err.code),
    };
  }
}

function getErrorMessage(code) {
  const messages = {
    ENODATA: 'DNS server returned answer with no data',
    EFORMERR: 'DNS server claims query was misformatted',
    ESERVFAIL: 'DNS server returned general failure',
    ENOTFOUND: 'Domain name not found',
    ENOTIMP: 'DNS server does not implement requested operation',
    EREFUSED: 'DNS server refused query',
    EBADQUERY: 'Misformatted DNS query',
    EBADNAME: 'Misformatted hostname',
    EBADFAMILY: 'Unsupported address family',
    EBADRESP: 'Misformatted DNS reply',
    ECONNREFUSED: 'Could not contact DNS servers',
    ETIMEOUT: 'Timeout while contacting DNS servers',
    EOF: 'End of file',
    EFILE: 'Error reading file',
    ENOMEM: 'Out of memory',
    EDESTRUCTION: 'Channel is being destroyed',
    EBADSTR: 'Misformatted string',
    EBADFLAGS: 'Illegal flags specified',
    ENONAME: 'Given hostname is not numeric',
    EBADHINTS: 'Illegal hints flags specified',
    ENOTINITIALIZED: 'c-ares library initialization not yet performed',
    ELOADIPHLPAPI: 'Error loading iphlpapi.dll',
    EADDRGETNETWORKPARAMS: 'Could not find GetNetworkParams function',
    ECANCELLED: 'DNS query cancelled',
  };
  return messages[code] || 'Unknown DNS error';
}

Caching DNS Results#

const dns = require('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) {
      return cached.result;
    }

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

    return result;
  }

  async resolve(hostname, recordType = 'A') {
    const key = `${hostname}:${recordType}`;
    const cached = this.cache.get(key);

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

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

    return result;
  }

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

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

async function lookupCached(hostname) {
  return dnsCache.lookup(hostname);
}

Practical Examples#

const dns = require('dns').promises;

// Validate email domain
async function validateEmailDomain(email) {
  const domain = email.split('@')[1];
  if (!domain) return false;

  try {
    const mxRecords = await dns.resolveMx(domain);
    return mxRecords.length > 0;
  } catch {
    return false;
  }
}

// Check domain availability
async function isDomainAvailable(domain) {
  try {
    await dns.lookup(domain);
    return false; // Domain resolves, not available
  } catch (err) {
    if (err.code === 'ENOTFOUND') {
      return true; // Domain doesn't resolve, might be available
    }
    throw err;
  }
}

// Get all DNS info for domain
async function getDomainInfo(domain) {
  const info = {
    domain,
    addresses: [],
    mx: [],
    ns: [],
    txt: [],
    soa: null,
  };

  try {
    info.addresses = await dns.resolve4(domain);
  } catch {}

  try {
    info.mx = await dns.resolveMx(domain);
  } catch {}

  try {
    info.ns = await dns.resolveNs(domain);
  } catch {}

  try {
    info.txt = await dns.resolveTxt(domain);
  } catch {}

  try {
    info.soa = await dns.resolveSoa(domain);
  } catch {}

  return info;
}

// Health check with DNS
async function checkDNSHealth(servers) {
  const results = await Promise.all(
    servers.map(async (server) => {
      const resolver = new dns.Resolver();
      resolver.setServers([server]);

      const start = Date.now();
      try {
        await resolver.resolve4('google.com');
        return {
          server,
          status: 'healthy',
          latency: Date.now() - start,
        };
      } catch (err) {
        return {
          server,
          status: 'unhealthy',
          error: err.message,
        };
      }
    })
  );

  return results;
}

Best Practices#

Usage:
✓ Use dns.promises for async/await
✓ Handle all error codes appropriately
✓ Implement caching for repeated lookups
✓ Use custom resolvers when needed

Performance:
✓ Cache DNS results with appropriate TTL
✓ Use parallel resolution when possible
✓ Consider using faster DNS servers
✓ Implement timeouts

Security:
✓ Validate hostnames before lookup
✓ Use DNSSEC when available
✓ Be aware of DNS rebinding attacks
✓ Log suspicious DNS queries

Avoid:
✗ Blocking the event loop with sync calls
✗ Ignoring DNS errors
✗ Hardcoding DNS servers in production
✗ Making DNS calls in hot paths

The dns module provides comprehensive DNS functionality for Node.js. Use dns.promises for modern async/await code, implement caching for performance, and handle errors appropriately. Consider using custom resolvers for specialized DNS requirements.